breaker_machines 0.13.2 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dab65770123fb6626a9112608ddeb784b1f623c6dd61ba59bd4f2094f8c73bb4
-  data.tar.gz: 572686fc3febc21058ea20c300667d09b466d427c0bcab98af4230e5e14c7ee3
+  metadata.gz: b13af2a00df3d691dde7793676b7106280bfc9badf16b83e74d672c9640a7a87
+  data.tar.gz: 213c6d184a208b56e8233c077d3a4d53675631dcba235f047c7aa41aad5c4f22
 SHA512:
-  metadata.gz: ba432f7aeda81bd88dd93ea8d1c0cb1c843cbc964bc3a31c6baf1359b4fb0a2c4873cd0e5d19ed0543ef5f3ba728f7e2de78a022f395abec3164465f8d562169
-  data.tar.gz: 43f4c0da0445a1c7e91a9a1ba24e8892d4ba10cf1891ab75c44704834a1026b20e23fa5830c23029b3dee4a04ca9bba51c2319f069b0b92bbf7abd910a445ad1
+  metadata.gz: 4cd735ec384cd14ba9528fabe2d0e478b71ea9eaf807e11ab823f171b2876587dc48fbce228b1a225a92d2aae6c4234fa5a802ef8f174612bc49444daba35acb
+  data.tar.gz: 9ef430d6cf3d0b7f4a0d56283c1904d2dbcf1119d7d675dba4043ccaae622521b2247d63892a83a9da2d4cd1610f04effba6f388b35e0e5cd2fd6a3390fe8529

data/lib/breaker_machines/async_circuit.rb

@@ -11,11 +11,11 @@ module BreakerMachines
     include Circuit::AsyncStateManagement
 
     # Additional async-specific methods
-    def call_async(&block)
+    def call_async(&)
       require 'async' unless defined?(::Async)
 
       Async do
-        call(&block)
+        call(&)
       end
     end
 

data/lib/breaker_machines/async_support.rb

@@ -18,32 +18,36 @@ module BreakerMachines
     end
 
     # Execute a call with async support (fiber-safe mode)
-    def execute_call_async(&)
+    def execute_call_async(admission, &)
+      completed = false
       start_time = BreakerMachines.monotonic_time
 
       begin
-        # Execute with hedged requests if enabled
-        result = if @config[:hedged_requests] || @config[:backends]
-                   execute_hedged(&)
-                 else
-                   execute_with_async_timeout(@config[:timeout], &)
-                 end
+        result = execute_async_operation(&)
 
-        record_success(BreakerMachines.monotonic_time - start_time)
-        handle_success
+        complete_call_success(admission, start_time)
+        completed = true
         result
       rescue StandardError => e
         # Re-raise if it's not an async timeout or configured exception
         raise unless e.is_a?(async_timeout_error_class) || @config[:exceptions].any? { |klass| e.is_a?(klass) }
 
-        record_failure(BreakerMachines.monotonic_time - start_time, e)
-        handle_failure
+        complete_call_failure(admission, start_time, e)
+        completed = true
         raise unless @config[:fallback]
 
         invoke_fallback_with_async(e)
+      ensure
+        release_abandoned_admission(admission) unless completed
       end
     end
 
+    def execute_async_operation(&)
+      return execute_hedged(&) if @config[:hedged_requests] || @config[:backends]
+
+      execute_with_async_timeout(@config[:timeout], &)
+    end
+
     # Execute a block with optional timeout using modern Async API
     def execute_with_async_timeout(timeout, &)
       if timeout
@@ -60,14 +64,7 @@ module BreakerMachines
       when BreakerMachines::DSL::ParallelFallbackWrapper
         invoke_parallel_fallbacks(@config[:fallback].fallbacks, error)
       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
-        result.is_a?(::Async::Task) ? result.wait : result
+        invoke_proc_fallback_async(@config[:fallback], error)
       when Array
         # Try each fallback in order until one succeeds
         last_error = error
@@ -85,6 +82,16 @@ module BreakerMachines
 
     private
 
+    def invoke_proc_fallback_async(fallback, error)
+      result = if @config[:owner]
+                 @config[:owner].instance_exec(error, &fallback)
+               else
+                 fallback.call(error)
+               end
+
+      result.is_a?(::Async::Task) ? result.wait : result
+    end
+
     def invoke_single_fallback_async(fallback, error)
       case fallback
       when Proc

data/lib/breaker_machines/circuit/admission.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # Admission reserves calls under short locks and tracks their state generation.
+    module Admission
+      extend ActiveSupport::Concern
+
+      Call = Data.define(:state, :state_epoch) do
+        def closed?
+          state == :closed
+        end
+
+        def half_open?
+          state == :half_open
+        end
+      end
+
+      private
+
+      def attempt_recovery_if_ready
+        return unless open? && reset_timeout_elapsed?
+
+        @mutex.with_write_lock do
+          attempt_recovery if open? && reset_timeout_elapsed?
+        end
+      end
+
+      def admit_call
+        @mutex.with_read_lock do
+          case status_name
+          when :closed
+            Call.new(state: :closed, state_epoch: @state_epoch.value)
+          when :half_open
+            admit_half_open_call
+          end
+        end
+      end
+
+      def admit_half_open_call
+        state_epoch = @state_epoch.value
+        new_attempts = @half_open_attempts.increment
+
+        return Call.new(state: :half_open, state_epoch:) if new_attempts <= @config[:half_open_calls]
+
+        # This caller lost the race for a probe slot.
+        @half_open_attempts.decrement
+        nil
+      end
+
+      def admission_current?(admission)
+        admission.state_epoch == @state_epoch.value
+      end
+
+      def handle_success(admission)
+        return unless admission.half_open?
+
+        @mutex.with_write_lock do
+          return unless admission_current?(admission) && half_open?
+
+          successful_attempts = @half_open_successes.increment
+          next unless successful_attempts >= @config[:half_open_calls] || success_threshold_reached?
+
+          @half_open_attempts.value = 0
+          @half_open_successes.value = 0
+          reset
+        end
+      end
+
+      def handle_failure(admission)
+        @mutex.with_write_lock do
+          return unless admission_current?(admission)
+
+          if admission.closed? && closed? && failure_threshold_exceeded?
+            trip
+          elsif admission.half_open? && half_open?
+            @half_open_attempts.value = 0
+            @half_open_successes.value = 0
+            trip
+          end
+        end
+      end
+
+      def release_abandoned_admission(admission)
+        return unless admission.half_open?
+
+        @mutex.with_write_lock do
+          next unless admission_current?(admission) && half_open?
+          next unless @half_open_attempts.value.positive?
+
+          @half_open_attempts.decrement
+        end
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/base.rb

@@ -10,6 +10,7 @@ module BreakerMachines
 
       included do
         include Circuit::Configuration
+        include Circuit::Admission
         include Circuit::Execution
         include Circuit::HedgedExecution
         include Circuit::Introspection
@@ -29,24 +30,29 @@ module BreakerMachines
         # Use global default storage if not specified
         @storage = @config[:storage] || create_default_storage
         @metrics = @config[:metrics]
+        initialize_runtime_state
+
+        restore_status_from_storage if @storage
+
+        # Register with global registry unless auto_register is disabled
+        BreakerMachines::Registry.instance.register(self) unless @config[:auto_register] == false
+      end
+
+      private
+
+      def initialize_runtime_state
         @opened_at = Concurrent::AtomicReference.new(nil)
         @half_open_attempts = Concurrent::AtomicFixnum.new(0)
         @half_open_successes = Concurrent::AtomicFixnum.new(0)
+        @state_epoch = Concurrent::AtomicFixnum.new(0)
         @mutex = Concurrent::ReentrantReadWriteLock.new
         @last_failure_at = Concurrent::AtomicReference.new(nil)
         @last_error = Concurrent::AtomicReference.new(nil)
 
         # Initialize semaphore for bulkheading if max_concurrent is set
         @semaphore = (Concurrent::Semaphore.new(@config[:max_concurrent]) if @config[:max_concurrent])
-
-        restore_status_from_storage if @storage
-
-        # Register with global registry unless auto_register is disabled
-        BreakerMachines::Registry.instance.register(self) unless @config[:auto_register] == false
       end
 
-      private
-
       def restore_status_from_storage
         stored_status = @storage.get_status(@name)
         return unless stored_status

data/lib/breaker_machines/circuit/execution.rb

@@ -31,100 +31,92 @@ module BreakerMachines
 
       private
 
-      def execute_with_state_check(&block)
-        # Check if we need to transition from open to half-open first
-        if open? && reset_timeout_elapsed?
-          @mutex.with_write_lock do
-            attempt_recovery if open? # Double-check after acquiring lock
-          end
-        end
+      def execute_with_state_check(&)
+        attempt_recovery_if_ready
 
         # Apply bulkheading first, outside of any locks
+        acquired = false
         if @semaphore
           acquired = @semaphore.try_acquire
-          unless acquired
-            # Reject immediately if we can't acquire semaphore
-            return reject_call_bulkhead
-          end
+          return reject_call_bulkhead unless acquired
         end
 
         begin
-          @mutex.with_read_lock do
-            case status_name
-            when :open
-              reject_call
-            when :half_open
-              handle_half_open_status(&block)
-            when :closed
-              handle_closed_status(&block)
-            end
+          admission = admit_call
+          unless admission
+            # An open-circuit fallback is user code and may yield. It must not
+            # retain a bulkhead permit or circuit lock while it runs.
+            @semaphore&.release if acquired
+            acquired = false
+            return reject_call
           end
+
+          execute_call(admission, &)
         ensure
           @semaphore&.release if @semaphore && acquired
         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)
+      def execute_call(admission, &)
         # Use async version if fiber_safe is enabled
         if @config[:fiber_safe]
           # Ensure async is loaded and included
           Execution.load_async_support unless respond_to?(:execute_call_async)
-          return execute_call_async(&block)
+          return execute_call_async(admission, &)
         end
 
+        execute_call_sync(admission, &)
+      end
+
+      def execute_call_sync(admission, &)
+        completed = false
         start_time = BreakerMachines.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 with hedged requests if enabled
-          result = if @config[:hedged_requests] || @config[:backends]
-                     execute_hedged(&block)
-                   else
-                     block.call
-                   end
-
-          record_success(BreakerMachines.monotonic_time - start_time)
-          handle_success
+          result = execute_sync_operation(&)
+          complete_call_success(admission, start_time)
+          completed = true
           result
         rescue *@config[:exceptions] => e
-          record_failure(BreakerMachines.monotonic_time - start_time, e)
-          handle_failure
+          complete_call_failure(admission, start_time, e)
+          completed = true
           raise unless @config[:fallback]
 
           invoke_fallback(e)
+        ensure
+          release_abandoned_admission(admission) unless completed
         end
       end
 
+      def execute_sync_operation(&)
+        warn_about_sync_timeout
+        return execute_hedged(&) if @config[:hedged_requests] || @config[:backends]
+
+        yield
+      end
+
+      def warn_about_sync_timeout
+        return unless @config[:timeout] && BreakerMachines.logger && BreakerMachines.config.log_events
+
+        # Forceful Ruby timeouts can interrupt code while it holds resources.
+        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
+
+      def complete_call_success(admission, start_time)
+        record_success(BreakerMachines.monotonic_time - start_time)
+        handle_success(admission)
+      end
+
+      def complete_call_failure(admission, start_time, error)
+        record_failure(BreakerMachines.monotonic_time - start_time, error)
+        handle_failure(admission)
+      end
+
       def reject_call
         @metrics&.record_rejection(@name)
         invoke_callback(:on_reject)
@@ -144,43 +136,6 @@ module BreakerMachines
         invoke_fallback(error)
       end
 
-      def handle_success
-        return unless half_open?
-
-        @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
-        return unless closed? || half_open?
-
-        @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?
         if @config[:use_rate_threshold]
           # Rate-based threshold

data/lib/breaker_machines/circuit/state_callbacks.rb

@@ -9,6 +9,7 @@ module BreakerMachines
       private
 
       def on_circuit_open
+        @state_epoch.increment
         @opened_at.value = BreakerMachines.monotonic_time
         @storage&.set_status(@name, :open, @opened_at.value)
         if @storage.respond_to?(:record_event_with_details)
@@ -20,6 +21,7 @@ module BreakerMachines
       end
 
       def on_circuit_close
+        @state_epoch.increment
         @opened_at.value = nil
         @last_error.value = nil
         @last_failure_at.value = nil
@@ -33,6 +35,7 @@ module BreakerMachines
       end
 
       def on_circuit_half_open
+        @state_epoch.increment
         @half_open_attempts.value = 0
         @half_open_successes.value = 0
         @storage&.set_status(@name, :half_open)

data/lib/breaker_machines/dsl/circuit_builder.rb

@@ -160,7 +160,7 @@ module BreakerMachines
         @config[:exceptions] = exceptions
       end
 
-      def fiber_safe(enabled = true) # rubocop:disable Style/OptionalBooleanParameter
+      def fiber_safe(enabled = true)
         @config[:fiber_safe] = enabled
       end
 

data/lib/breaker_machines/dsl.rb

@@ -39,12 +39,12 @@ module BreakerMachines
         end
       end
 
-      def circuit(name, &block)
+      def circuit(name, &)
         @circuits ||= {}
 
         if block_given?
           builder = DSL::CircuitBuilder.new
-          builder.instance_eval(&block)
+          builder.instance_eval(&)
           @circuits[name] = builder.config
         end
 
@@ -52,12 +52,12 @@ module BreakerMachines
       end
 
       # Define a cascading circuit breaker that can trip dependent circuits
-      def cascade_circuit(name, &block)
+      def cascade_circuit(name, &)
         @circuits ||= {}
 
         if block_given?
           builder = DSL::CascadingCircuitBuilder.new
-          builder.instance_eval(&block)
+          builder.instance_eval(&)
           @circuits[name] = builder.config.merge(circuit_type: :cascading)
         end
 
@@ -81,12 +81,12 @@ module BreakerMachines
       end
 
       # Define reusable circuit templates
-      def circuit_template(name, &block)
+      def circuit_template(name, &)
         @circuit_templates ||= {}
 
         if block_given?
           builder = DSL::CircuitBuilder.new
-          builder.instance_eval(&block)
+          builder.instance_eval(&)
           @circuit_templates[name] = builder.config
         end
 

data/lib/breaker_machines/registry.rb

@@ -60,7 +60,7 @@ module BreakerMachines
     end
 
     # Force open a circuit by name
-    def force_open(name) # rubocop:disable Naming/PredicateMethod
+    def force_open(name)
       circuits = find_by_name(name)
       return false if circuits.empty?
 
@@ -69,7 +69,7 @@ module BreakerMachines
     end
 
     # Force close a circuit by name
-    def force_close(name) # rubocop:disable Naming/PredicateMethod
+    def force_close(name)
       circuits = find_by_name(name)
       return false if circuits.empty?
 
@@ -78,7 +78,7 @@ module BreakerMachines
     end
 
     # Reset a circuit by name
-    def reset(name) # rubocop:disable Naming/PredicateMethod
+    def reset(name)
       circuits = find_by_name(name)
       return false if circuits.empty?
 

data/lib/breaker_machines/storage/fallback_chain.rb

@@ -80,7 +80,7 @@ module BreakerMachines
 
       private
 
-      def execute_with_fallback(method, *args, **kwargs)
+      def execute_with_fallback(method, *, **kwargs)
         chain_started_at = BreakerMachines.monotonic_time
         attempted_backends = []
 
@@ -100,9 +100,9 @@ module BreakerMachines
 
             result = backend.with_timeout(config[:timeout]) do
               if kwargs.any?
-                backend.send(method, *args, **kwargs)
+                backend.send(method, *, **kwargs)
               else
-                backend.send(method, *args)
+                backend.send(method, *)
               end
             end
 

data/lib/breaker_machines/version.rb

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

data/sig/breaker_machines/circuit.rbs

@@ -2,6 +2,7 @@ module BreakerMachines
   class Circuit
     include StateManagement
     include Configuration
+    include Admission
     include Execution
     include Introspection
     include Callbacks
@@ -14,6 +15,7 @@ module BreakerMachines
     @opened_at: Concurrent::AtomicReference[Float?]
     @half_open_attempts: Concurrent::AtomicFixnum
     @half_open_successes: Concurrent::AtomicFixnum
+    @state_epoch: Concurrent::AtomicFixnum
     @mutex: Concurrent::ReentrantReadWriteLock
     @last_failure_at: Concurrent::AtomicReference[Float?]
     @last_error: Concurrent::AtomicReference[StandardError?]
@@ -22,6 +24,27 @@ module BreakerMachines
     attr_reader status: (:open | :closed | :half_open)
   end
 
+  module Admission
+    class Call
+      attr_reader state: (:closed | :half_open)
+      attr_reader state_epoch: Integer
+
+      def self.new: (state: (:closed | :half_open), state_epoch: Integer) -> Call
+      def closed?: () -> bool
+      def half_open?: () -> bool
+    end
+
+    private
+
+    def attempt_recovery_if_ready: () -> void
+    def admit_call: () -> Call?
+    def admit_half_open_call: () -> Call?
+    def admission_current?: (Call admission) -> bool
+    def handle_success: (Call admission) -> void
+    def handle_failure: (Call admission) -> void
+    def release_abandoned_admission: (Call admission) -> void
+  end
+
   module StateManagement
     interface _StateManagementState
       def status: () -> (:open | :closed | :half_open)
@@ -96,13 +119,15 @@ module BreakerMachines
 
     private
 
-    def handle_open_status: () { () -> untyped } -> untyped
-    def handle_half_open_status: () { () -> untyped } -> untyped
-    def handle_closed_status: () { () -> untyped } -> untyped
-    def execute_call: () { () -> untyped } -> untyped
+    def execute_with_state_check: [T] () { () -> T } -> untyped
+    def execute_call: [T] (Admission::Call admission) { () -> T } -> untyped
+    def execute_call_sync: [T] (Admission::Call admission) { () -> T } -> untyped
+    def execute_sync_operation: [T] () { () -> T } -> T
+    def warn_about_sync_timeout: () -> void
+    def complete_call_success: (Admission::Call admission, Float start_time) -> void
+    def complete_call_failure: (Admission::Call admission, Float start_time, Exception error) -> void
     def reject_call: () -> untyped
-    def handle_success: () -> void
-    def handle_failure: () -> void
+    def reject_call_bulkhead: () -> untyped
     def failure_threshold_exceeded?: () -> bool
     def success_threshold_reached?: () -> bool
     def record_success: (Float duration) -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: breaker_machines
 version: !ruby/object:Gem::Version
-  version: 0.13.2
+  version: 0.18.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -55,16 +55,16 @@ dependencies:
   name: state_machines
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.200.0
+        version: '0.202'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.200.0
+        version: '0.202'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -154,6 +154,7 @@ files:
 - lib/breaker_machines/async_support.rb
 - lib/breaker_machines/cascading_circuit.rb
 - lib/breaker_machines/circuit.rb
+- lib/breaker_machines/circuit/admission.rb
 - lib/breaker_machines/circuit/async_state_management.rb
 - lib/breaker_machines/circuit/base.rb
 - lib/breaker_machines/circuit/callbacks.rb
@@ -221,14 +222,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.3.0
+      version: 4.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Circuit breaker implementation for Ruby with a clean DSL and state_machines
   under the hood