breaker_machines 0.1.0

data/lib/breaker_machines/circuit/callbacks.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Callbacks handles the invocation of user-defined callbacks and fallback mechanisms
+    # when circuit state changes occur or calls are rejected.
+    module Callbacks
+      extend ActiveSupport::Concern
+
+      private
+
+      def invoke_callback(callback_name)
+        callback = @config[callback_name]
+        return unless callback
+
+        return unless callback.is_a?(Proc)
+
+        if @config[:owner]
+          @config[:owner].instance_exec(&callback)
+        else
+          callback.call
+        end
+      end
+
+      def invoke_fallback(error)
+        case @config[:fallback]
+        when Proc
+          if @config[:owner]
+            @config[:owner].instance_exec(error, &@config[:fallback])
+          else
+            @config[:fallback].call(error)
+          end
+        when Array
+          # Try each fallback in order until one succeeds
+          last_error = error
+          @config[:fallback].each do |fallback|
+            return invoke_single_fallback(fallback, last_error)
+          rescue StandardError => e
+            last_error = e
+          end
+          raise last_error
+        else
+          # Static values (strings, hashes, etc.) or Symbol fallbacks
+          @config[:fallback]
+        end
+      end
+
+      def invoke_single_fallback(fallback, error)
+        case fallback
+        when Proc
+          if @config[:owner]
+            @config[:owner].instance_exec(error, &fallback)
+          else
+            fallback.call(error)
+          end
+        else
+          fallback
+        end
+      end
+
+      # Async versions for fiber_safe mode
+      def invoke_callback_async(callback_name)
+        callback = @config[callback_name]
+        return unless callback
+        return unless callback.is_a?(Proc)
+
+        result = if @config[:owner]
+                   @config[:owner].instance_exec(&callback)
+                 else
+                   callback.call
+                 end
+
+        # If the callback returns an Async::Task, wait for it
+        if defined?(::Async::Task) && result.is_a?(::Async::Task)
+          result.wait
+        else
+          result
+        end
+      end
+
+      def invoke_fallback_async(error)
+        case @config[:fallback]
+        when Proc
+          result = if @config[:owner]
+                     @config[:owner].instance_exec(error, &@config[:fallback])
+                   else
+                     @config[:fallback].call(error)
+                   end
+
+          # If the fallback returns an Async::Task, wait for it
+          if defined?(::Async::Task) && result.is_a?(::Async::Task)
+            result.wait
+          else
+            result
+          end
+        when Array
+          # Try each fallback in order until one succeeds
+          last_error = error
+          @config[:fallback].each do |fallback|
+            return invoke_single_fallback_async(fallback, last_error)
+          rescue StandardError => e
+            last_error = e
+          end
+          raise last_error
+        else
+          # Static values (strings, hashes, etc.) or Symbol fallbacks
+          @config[:fallback]
+        end
+      end
+
+      def invoke_single_fallback_async(fallback, error)
+        case fallback
+        when Proc
+          result = if @config[:owner]
+                     @config[:owner].instance_exec(error, &fallback)
+                   else
+                     fallback.call(error)
+                   end
+
+          # If the fallback returns an Async::Task, wait for it
+          if defined?(::Async::Task) && result.is_a?(::Async::Task)
+            result.wait
+          else
+            result
+          end
+        else
+          fallback
+        end
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/configuration.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Configuration manages circuit initialization and default settings,
+    # including thresholds, timeouts, storage backends, and callbacks.
+    module Configuration
+      extend ActiveSupport::Concern
+
+      included do
+        attr_reader :name, :config, :opened_at
+      end
+
+      def initialize(name, options = {})
+        @name = name
+        @config = default_config.merge(options)
+        # Always use a storage backend for proper sliding window implementation
+        # Use global default storage if not specified
+        @storage = @config[:storage] || create_default_storage
+        @metrics = @config[:metrics]
+        @opened_at = Concurrent::AtomicReference.new(nil)
+        @half_open_attempts = Concurrent::AtomicFixnum.new(0)
+        @half_open_successes = Concurrent::AtomicFixnum.new(0)
+        @mutex = Concurrent::ReentrantReadWriteLock.new
+        @last_failure_at = Concurrent::AtomicReference.new(nil)
+        @last_error = Concurrent::AtomicReference.new(nil)
+
+        super() # Initialize state machine
+        restore_status_from_storage if @storage
+
+        # Register with global registry
+        BreakerMachines::Registry.instance.register(self)
+      end
+
+      private
+
+      def default_config
+        {
+          failure_threshold: 5,
+          failure_window: 60, # seconds
+          success_threshold: 1,
+          timeout: nil,
+          reset_timeout: 60, # seconds
+          reset_timeout_jitter: 0.25, # +/- 25% by default
+          half_open_calls: 1,
+          storage: nil, # Will default to Memory storage if nil
+          metrics: nil,
+          fallback: nil,
+          on_open: nil,
+          on_close: nil,
+          on_half_open: nil,
+          on_reject: nil,
+          exceptions: [StandardError],
+          fiber_safe: BreakerMachines.config.fiber_safe
+        }
+      end
+
+      def create_default_storage
+        case BreakerMachines.config.default_storage
+        when :memory
+          BreakerMachines::Storage::Memory.new
+        when :bucket_memory
+          BreakerMachines::Storage::BucketMemory.new
+        when :null
+          BreakerMachines::Storage::Null.new
+        else
+          # Allow for custom storage class names
+          BreakerMachines.config.default_storage.new
+        end
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/execution.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Execution handles the core circuit breaker logic including call wrapping,
+    # state-based request handling, and failure/success tracking.
+    module Execution
+      extend ActiveSupport::Concern
+
+      # Lazy load async support only when needed
+      def self.load_async_support
+        require 'async'
+        require 'async/task'
+      rescue LoadError
+        raise LoadError, "The 'async' gem is required for fiber_safe mode. Add `gem 'async'` to your Gemfile."
+      end
+
+      def call(&)
+        wrap(&)
+      end
+
+      def wrap(&block)
+        @mutex.with_read_lock do
+          case status_name
+          when :open
+            handle_open_status(&block)
+          when :half_open
+            handle_half_open_status(&block)
+          when :closed
+            handle_closed_status(&block)
+          end
+        end
+      end
+
+      private
+
+      def handle_open_status(&)
+        if reset_timeout_elapsed?
+          @mutex.with_write_lock do
+            attempt_recovery if open?
+          end
+          handle_half_open_status(&)
+        else
+          reject_call
+        end
+      end
+
+      def handle_half_open_status(&)
+        # Atomically increment and get the new value
+        new_attempts = @half_open_attempts.increment
+
+        if new_attempts <= @config[:half_open_calls]
+          execute_call(&)
+        else
+          # This thread lost the race, decrement back and reject
+          @half_open_attempts.decrement
+          reject_call
+        end
+      end
+
+      def handle_closed_status(&)
+        execute_call(&)
+      end
+
+      def execute_call(&block)
+        # Use async version if fiber_safe is enabled
+        return execute_call_async(&block) if @config[:fiber_safe]
+
+        start_time = monotonic_time
+
+        begin
+          # IMPORTANT: We do NOT implement forceful timeouts as they are inherently unsafe
+          # The timeout configuration is provided for documentation/intent purposes
+          # Users should implement timeouts in their own code using safe mechanisms
+          # (e.g., HTTP client timeouts, database statement timeouts, etc.)
+          # Log a warning if timeout is configured
+          if @config[:timeout] && BreakerMachines.logger && BreakerMachines.config.log_events
+            BreakerMachines.logger.warn(
+              "[BreakerMachines] Circuit '#{@name}' has timeout configured but " \
+              'forceful timeouts are not implemented for safety. ' \
+              'Please use timeout mechanisms provided by your libraries ' \
+              '(e.g., Net::HTTP read_timeout, ActiveRecord statement_timeout).'
+            )
+          end
+
+          # Execute normally without forceful timeout
+          result = block.call
+
+          record_success(monotonic_time - start_time)
+          handle_success
+          result
+        rescue *@config[:exceptions] => e
+          record_failure(monotonic_time - start_time, e)
+          handle_failure
+          raise unless @config[:fallback]
+
+          invoke_fallback(e)
+        end
+      end
+
+      def execute_call_async(&)
+        # Ensure async is loaded
+        Execution.load_async_support unless defined?(::Async)
+
+        start_time = monotonic_time
+
+        begin
+          result = if @config[:timeout]
+                     # Use safe, cooperative timeout from async gem
+                     ::Async::Task.current.with_timeout(@config[:timeout], &)
+                   else
+                     yield
+                   end
+
+          record_success(monotonic_time - start_time)
+          handle_success
+          result
+        rescue ::Async::TimeoutError => e
+          # Handle async timeout as a failure
+          record_failure(monotonic_time - start_time, e)
+          handle_failure
+          raise unless @config[:fallback]
+
+          invoke_fallback_async(e)
+        rescue *@config[:exceptions] => e
+          record_failure(monotonic_time - start_time, e)
+          handle_failure
+          raise unless @config[:fallback]
+
+          invoke_fallback_async(e)
+        end
+      end
+
+      def reject_call
+        @metrics&.record_rejection(@name)
+        invoke_callback(:on_reject)
+
+        raise BreakerMachines::CircuitOpenError.new(@name, @opened_at.value) unless @config[:fallback]
+
+        invoke_fallback(BreakerMachines::CircuitOpenError.new(@name, @opened_at.value))
+      end
+
+      def handle_success
+        @mutex.with_write_lock do
+          if half_open?
+            # Check if all allowed half-open calls have succeeded
+            # This ensures the circuit can close even if success_threshold > half_open_calls
+            successful_attempts = @half_open_successes.increment
+
+            # Fast-close logic: Circuit closes if EITHER:
+            # 1. All allowed half-open calls succeeded (conservative approach)
+            # 2. Success threshold is reached (aggressive approach for quick recovery)
+            # This allows flexible configuration - set success_threshold=1 for fast recovery
+            # or success_threshold=half_open_calls for cautious recovery
+            if successful_attempts >= @config[:half_open_calls] || success_threshold_reached?
+              @half_open_attempts.value = 0
+              @half_open_successes.value = 0
+              reset
+            end
+          end
+        end
+      end
+
+      def handle_failure
+        @mutex.with_write_lock do
+          if closed? && failure_threshold_exceeded?
+            trip
+          elsif half_open?
+            @half_open_attempts.value = 0
+            @half_open_successes.value = 0
+            trip
+          end
+        end
+      end
+
+      def failure_threshold_exceeded?
+        recent_failures = @storage.failure_count(@name, @config[:failure_window])
+        recent_failures >= @config[:failure_threshold]
+      end
+
+      def success_threshold_reached?
+        recent_successes = @storage.success_count(@name, @config[:failure_window])
+        recent_successes >= @config[:success_threshold]
+      end
+
+      def record_success(duration)
+        @metrics&.record_success(@name, duration)
+        @storage&.record_success(@name, duration)
+        return unless @storage.respond_to?(:record_event_with_details)
+
+        @storage.record_event_with_details(@name, :success,
+                                           duration)
+      end
+
+      def record_failure(duration, error = nil)
+        @last_failure_at.value = monotonic_time
+        @last_error.value = error if error
+        @metrics&.record_failure(@name, duration)
+        @storage&.record_failure(@name, duration)
+        return unless @storage.respond_to?(:record_event_with_details)
+
+        @storage.record_event_with_details(@name, :failure, duration,
+                                           error: error)
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/introspection.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Introspection provides methods for inspecting circuit state, statistics,
+    # and generating human-readable summaries of circuit status.
+    module Introspection
+      extend ActiveSupport::Concern
+      # State check methods are automatically generated by state_machines:
+      # - open? (returns true when status == :open)
+      # - closed? (returns true when status == :closed)
+      # - half_open? (returns true when status == :half_open)
+
+      def stats
+        {
+          state: status_name,
+          failure_count: @storage.failure_count(@name, @config[:failure_window]),
+          success_count: @storage.success_count(@name, @config[:failure_window]),
+          last_failure_at: @last_failure_at.value,
+          opened_at: @opened_at.value,
+          half_open_attempts: @half_open_attempts.value,
+          half_open_successes: @half_open_successes.value
+        }
+      end
+
+      def configuration
+        @config.dup
+      end
+
+      def event_log(limit: 20)
+        @storage.event_log(@name, limit) if @storage.respond_to?(:event_log)
+      end
+
+      def last_error
+        @last_error.value
+      end
+
+      def to_h
+        {
+          name: @name,
+          state: status_name,
+          stats: stats,
+          config: configuration.except(:owner, :storage, :metrics),
+          event_log: event_log || [],
+          last_error: last_error_info
+        }
+      end
+
+      def summary
+        case status_name
+        when :closed
+          "Circuit '#{@name}' is CLOSED. #{stats[:failure_count]} failures recorded."
+        when :open
+          reset_time = Time.at(@opened_at.value + @config[:reset_timeout])
+          opened_time = Time.at(@opened_at.value)
+          error_info = @last_error.value ? " The last error was #{@last_error.value.class}." : ''
+          "Circuit '#{@name}' is OPEN until #{reset_time}. " \
+            "It opened at #{opened_time} after #{@config[:failure_threshold]} failures.#{error_info}"
+        when :half_open
+          "Circuit '#{@name}' is HALF-OPEN. Testing with limited requests " \
+          "(#{@half_open_attempts.value}/#{@config[:half_open_calls]} attempts)."
+        end
+      end
+
+      def last_error_info
+        error = @last_error.value
+        return nil unless error
+
+        {
+          class: error.class.name,
+          message: error.message,
+          occurred_at: @last_failure_at.value
+        }
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/state_management.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # StateManagement provides the state machine functionality for circuit breakers,
+    # managing transitions between closed, open, and half-open states.
+    module StateManagement
+      extend ActiveSupport::Concern
+      included do
+        state_machine :status, initial: :closed do
+          event :trip do
+            transition closed: :open
+            transition half_open: :open
+          end
+
+          event :attempt_recovery do
+            transition open: :half_open
+          end
+
+          event :reset do
+            transition %i[open half_open] => :closed
+          end
+
+          event :force_open do
+            transition any => :open
+          end
+
+          event :force_close do
+            transition any => :closed
+          end
+
+          after_transition any => :open do |circuit|
+            circuit.send(:on_circuit_open)
+          end
+
+          after_transition any => :closed do |circuit|
+            circuit.send(:on_circuit_close)
+          end
+
+          after_transition open: :half_open do |circuit|
+            circuit.send(:on_circuit_half_open)
+          end
+        end
+      end
+
+      private
+
+      def on_circuit_open
+        @opened_at.value = monotonic_time
+        @storage&.set_status(@name, :open, @opened_at.value)
+        if @storage.respond_to?(:record_event_with_details)
+          @storage.record_event_with_details(@name, :state_change, 0,
+                                             new_state: :open)
+        end
+        invoke_callback(:on_open)
+        BreakerMachines.instrument('opened', circuit: @name)
+      end
+
+      def on_circuit_close
+        @opened_at.value = nil
+        @last_error.value = nil
+        @last_failure_at.value = nil
+        @storage&.set_status(@name, :closed)
+        if @storage.respond_to?(:record_event_with_details)
+          @storage.record_event_with_details(@name, :state_change, 0,
+                                             new_state: :closed)
+        end
+        invoke_callback(:on_close)
+        BreakerMachines.instrument('closed', circuit: @name)
+      end
+
+      def on_circuit_half_open
+        @half_open_attempts.value = 0
+        @half_open_successes.value = 0
+        @storage&.set_status(@name, :half_open)
+        if @storage.respond_to?(:record_event_with_details)
+          @storage.record_event_with_details(@name, :state_change, 0,
+                                             new_state: :half_open)
+        end
+        invoke_callback(:on_half_open)
+        BreakerMachines.instrument('half_opened', circuit: @name)
+      end
+
+      def restore_status_from_storage
+        stored_status = @storage.get_status(@name)
+        return unless stored_status
+
+        self.status = stored_status[:status].to_s
+        @opened_at.value = stored_status[:opened_at] if stored_status[:opened_at]
+      end
+
+      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
+
+        monotonic_time - @opened_at.value >= timeout_with_jitter
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'state_machines'
+require 'concurrent-ruby'
+
+module BreakerMachines
+  class Circuit
+    include StateManagement
+    include Configuration
+    include Execution
+    include Introspection
+    include Callbacks
+  end
+end