semian 0.27.0 → 0.28.0

data/lib/semian.rb

@@ -11,6 +11,8 @@ require "semian/instrumentable"
 require "semian/platform"
 require "semian/resource"
 require "semian/circuit_breaker"
+require "semian/adaptive_circuit_breaker"
+require "semian/dual_circuit_breaker"
 require "semian/protected_resource"
 require "semian/unprotected_resource"
 require "semian/simple_sliding_window"
@@ -197,6 +199,32 @@ module Semian
   # +exceptions+: An array of exception classes that should be accounted as resource errors. Default [].
   # (circuit breaker)
   #
+  #   # +exponential_backoff_error_timeout+: When set to true, instead of opening the circuit for the full
+  # error_timeout duration, it starts with a smaller timeout and increases exponentially on each subsequent
+  # opening up to error_timeout. This helps avoid over-opening the circuit for temporary issues.
+  # Default false. (circuit breaker)
+  #
+  # +exponential_backoff_initial_timeout+: The initial timeout in seconds when exponential backoff is enabled.
+  # Only valid when exponential_backoff_error_timeout is true. Default 1. (circuit breaker)
+  #
+  # +exponential_backoff_multiplier+: The factor by which to multiply the timeout on each subsequent opening
+  # when exponential backoff is enabled. Only valid when exponential_backoff_error_timeout is true.
+  # Default 2. (circuit breaker)
+  #
+  # +adaptive_circuit_breaker+: Enable adaptive circuit breaker using PID controller. Default false.
+  # When enabled, this replaces the traditional circuit breaker with an adaptive version
+  # that dynamically adjusts rejection rates based on service health. (adaptive circuit breaker)
+  #
+  # +dual_circuit_breaker+: Enable dual circuit breaker mode where both legacy and adaptive
+  # circuit breakers are initialized. Default false. When enabled, both circuit breakers track
+  # requests, but only one is used for decision-making based on use_adaptive.
+  # (dual circuit breaker)
+  #
+  # +use_adaptive+: A callable (Proc/lambda) that returns true to use adaptive circuit breaker
+  # or false to use legacy. Only used when dual_circuit_breaker is enabled. Default: ->() { false }.
+  # Example: ->() { MyFeatureFlag.enabled?(:adaptive_circuit_breaker) }
+  # (dual circuit breaker)
+  #
   # Returns the registered resource.
   def register(name, **options)
     return UnprotectedResource.new(name) if ENV.key?("SEMIAN_DISABLED")
@@ -204,7 +232,14 @@ module Semian
     # Validate configuration before proceeding
     ConfigurationValidator.new(name, options).validate!
 
-    circuit_breaker = create_circuit_breaker(name, **options)
+    circuit_breaker = if options[:dual_circuit_breaker]
+      create_dual_circuit_breaker(name, **options)
+    elsif options[:adaptive_circuit_breaker]
+      create_adaptive_circuit_breaker(name, **options)
+    else
+      create_circuit_breaker(name, **options)
+    end
+
     bulkhead = create_bulkhead(name, **options)
 
     resources[name] = ProtectedResource.new(name, bulkhead, circuit_breaker)
@@ -300,12 +335,49 @@ module Semian
 
   private
 
-  def create_circuit_breaker(name, **options)
+  def create_dual_circuit_breaker(name, **options)
+    return if ENV.key?("SEMIAN_CIRCUIT_BREAKER_DISABLED")
+
+    classic_cb = create_circuit_breaker(name, is_child: true, **options)
+    adaptive_cb = create_adaptive_circuit_breaker(name, is_child: true, **options)
+
+    DualCircuitBreaker.new(
+      name: name,
+      classic_circuit_breaker: classic_cb,
+      adaptive_circuit_breaker: adaptive_cb,
+    )
+  end
+
+  def create_adaptive_circuit_breaker(name, is_child: false, **options)
+    return if ENV.key?("SEMIAN_CIRCUIT_BREAKER_DISABLED")
+
+    exceptions = options[:exceptions] || []
+    cls = is_child ? DualCircuitBreaker::ChildAdaptiveCircuitBreaker : AdaptiveCircuitBreaker
+    cls.new(
+      name: name,
+      exceptions: Array(exceptions) + [::Semian::BaseError],
+      kp: options[:kp] || 1.0,
+      ki: options[:ki] || 0.2,
+      kd: options[:kd] || 0.0,
+      window_size: options[:window_size] || 10,
+      initial_error_rate: options[:initial_error_rate] || 0.05,
+      dead_zone_ratio: options[:dead_zone_ratio] || 0.25,
+      # We use an environment vraiable for the sliding interval because it is shared among all circuit breakers
+      sliding_interval: ENV.fetch("SEMIAN_ADAPTIVE_CIRCUIT_BREAKER_SLIDING_INTERVAL", 1).to_i,
+      ideal_error_rate_estimator_cap_value: options[:ideal_error_rate_estimator_cap_value] || 0.1,
+      integral_upper_cap: options[:integral_upper_cap] || 10.0,
+      integral_lower_cap: options[:integral_lower_cap] || -10.0,
+      implementation: implementation(**options),
+    )
+  end
+
+  def create_circuit_breaker(name, is_child: false, **options)
     return if ENV.key?("SEMIAN_CIRCUIT_BREAKER_DISABLED")
     return unless options.fetch(:circuit_breaker, true)
 
     exceptions = options[:exceptions] || []
-    CircuitBreaker.new(
+    cls = is_child ? DualCircuitBreaker::ChildClassicCircuitBreaker : CircuitBreaker
+    cls.new(
       name,
       success_threshold: options[:success_threshold],
       error_threshold: options[:error_threshold],
@@ -323,6 +395,9 @@ module Semian
                         end,
       exceptions: Array(exceptions) + [::Semian::BaseError],
       half_open_resource_timeout: options[:half_open_resource_timeout],
+      exponential_backoff_error_timeout: options[:exponential_backoff_error_timeout] || false,
+      exponential_backoff_initial_timeout: options[:exponential_backoff_initial_timeout] || 1,
+      exponential_backoff_multiplier: options[:exponential_backoff_multiplier] || 2,
       implementation: implementation(**options),
     )
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: semian
 version: !ruby/object:Gem::Version
-  version: 0.27.0
+  version: 0.28.0
 platform: ruby
 authors:
 - Scott Francis
@@ -51,13 +51,18 @@ files:
 - lib/semian/activerecord_postgresql_adapter.rb
 - lib/semian/activerecord_trilogy_adapter.rb
 - lib/semian/adapter.rb
+- lib/semian/adaptive_circuit_breaker.rb
 - lib/semian/circuit_breaker.rb
+- lib/semian/circuit_breaker_behaviour.rb
 - lib/semian/configuration_validator.rb
+- lib/semian/dual_circuit_breaker.rb
 - lib/semian/grpc.rb
 - lib/semian/instrumentable.rb
 - lib/semian/lru_hash.rb
 - lib/semian/mysql2.rb
 - lib/semian/net_http.rb
+- lib/semian/pid_controller.rb
+- lib/semian/pid_controller_thread.rb
 - lib/semian/platform.rb
 - lib/semian/protected_resource.rb
 - lib/semian/rails.rb
@@ -65,6 +70,7 @@ files:
 - lib/semian/redis/v5.rb
 - lib/semian/redis_client.rb
 - lib/semian/resource.rb
+- lib/semian/simple_exponential_smoother.rb
 - lib/semian/simple_integer.rb
 - lib/semian/simple_sliding_window.rb
 - lib/semian/simple_state.rb
@@ -94,7 +100,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Bulkheading for Ruby with SysV semaphores
 test_files: []