semian 0.27.0 → 0.27.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc25bcc8e0291e3f53d1ecb6ac19e56b375ce0c16974d16c20b9a847b6d2104d
-  data.tar.gz: 8c4ab8f6259e8118fa94801b28392738a05403d346941738f68bea258bc41f37
+  metadata.gz: b84efc35cf9e47382fc7ac82d69ff0bfb55028eb79c8e4d76127b1e4ee8b7053
+  data.tar.gz: 0e16ab39a45133600134574abd65012dae026cfa1f1020695974edf46d00d41d
 SHA512:
-  metadata.gz: 4f0936f08aa93d042241bece483742cc03d9e50ebaf27a363aec1973026d989ee3c6c6067de13f9016a46b5a227fb40ac2136746c8da25d33895f5a4312da510
-  data.tar.gz: 6cada0bbab474810b4bc12617e2d6e323034e6b088cebfa0d41352f0f1c8e522b4fc37d2e9dde77328c1ac5a7fc76e34e76b94f313313da9363049a72fb83859
+  metadata.gz: abb82539122c2b4ef05420bc996d67cbcd0da9cafd3c735cd85547dd3691af6a6e287f52034d9e2870195ee13708f94e3edf68ad11962e2ad0b6c9023e4243ec
+  data.tar.gz: 9041cb2e5834339f584c951558ea071dfd91afc1502971495ab55890963c0ce401ac5b7b1b51611f1d51a3d81618dafb2f2ab648ec8811d7f20f999face6653d

data/README.md

@@ -588,6 +588,10 @@ There are four configuration parameters for circuit breakers in Semian:
   Defaults to `error_timeout` seconds if not set.
 - **error_timeout**. The amount of time in seconds until trying to query the resource
   again.
+- **exponential_backoff_error_timeout**. If set to `true`, we will progress towards error_timeout exponentially, instead of committing to it directly.
+This is useful to avoid rejecting too many requests if the dependency is not really degraded.
+- **exponential_backoff_initial_timeout**. Where to start the exponential backoff towards `error_timeout` from. Defaults to 1 second.
+- **exponential_backoff_multiplier**. The exponential multiplier to use during the exponential backoff towards the `error_timeout`. Defaults to 2.
 - **error_threshold_timeout_enabled**. If set to false it will disable
   the time window for evicting old exceptions. `error_timeout` is still used and
   will reset the circuit. Defaults to `true` if not set.

data/lib/semian/circuit_breaker.rb

@@ -13,12 +13,16 @@ module Semian
       :state,
       :last_error,
       :error_threshold_timeout_enabled,
+      :exponential_backoff_error_timeout,
+      :exponential_backoff_initial_timeout,
+      :exponential_backoff_multiplier,
     )
 
     def initialize(name, exceptions:, success_threshold:, error_threshold:,
       error_timeout:, implementation:, half_open_resource_timeout: nil,
       error_threshold_timeout: nil, error_threshold_timeout_enabled: true,
-      lumping_interval: 0)
+      lumping_interval: 0, exponential_backoff_error_timeout: false,
+      exponential_backoff_initial_timeout: 1, exponential_backoff_multiplier: 2)
       @name = name.to_sym
       @success_count_threshold = success_threshold
       @error_count_threshold = error_threshold
@@ -28,6 +32,10 @@ module Semian
       @exceptions = exceptions
       @half_open_resource_timeout = half_open_resource_timeout
       @lumping_interval = lumping_interval
+      @exponential_backoff_error_timeout = exponential_backoff_error_timeout
+      @exponential_backoff_initial_timeout = exponential_backoff_initial_timeout
+      @exponential_backoff_multiplier = exponential_backoff_multiplier
+      @current_error_timeout = exponential_backoff_error_timeout ? exponential_backoff_initial_timeout : error_timeout
 
       @errors = implementation::SlidingWindow.new(max_size: @error_count_threshold)
       @successes = implementation::Integer.new
@@ -102,6 +110,8 @@ module Semian
       log_state_transition(:closed)
       @state.close!
       @errors.clear
+      # Reset exponential backoff when circuit closes
+      @current_error_timeout = @exponential_backoff_error_timeout ? @exponential_backoff_initial_timeout : @error_timeout
     end
 
     def transition_to_open
@@ -115,6 +125,10 @@ module Semian
       log_state_transition(:half_open)
       @state.half_open!
       @successes.reset
+      # Multiply the backoff timeout when circuit opens (up to the max error_timeout)
+      if @exponential_backoff_error_timeout && @current_error_timeout < @error_timeout
+        @current_error_timeout = [@current_error_timeout * @exponential_backoff_multiplier, @error_timeout].min
+      end
     end
 
     def success_threshold_reached?
@@ -129,7 +143,7 @@ module Semian
       last_error_time = @errors.last
       return false unless last_error_time
 
-      last_error_time + @error_timeout < Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      last_error_time + @current_error_timeout < Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
     def push_error(error)
@@ -153,6 +167,9 @@ module Semian
       str += " success_count_threshold=#{@success_count_threshold}"
       str += " error_count_threshold=#{@error_count_threshold}"
       str += " error_timeout=#{@error_timeout} error_last_at=\"#{@errors.last}\""
+      if @exponential_backoff_error_timeout
+        str += " current_error_timeout=#{@current_error_timeout}"
+      end
       str += " name=\"#{@name}\""
       if new_state == :open && @last_error
         str += " last_error_message=#{@last_error.message.inspect}"

data/lib/semian/configuration_validator.rb

@@ -103,6 +103,7 @@ module Semian
       error_threshold = @configuration[:error_threshold]
       lumping_interval = @configuration[:lumping_interval]
       half_open_resource_timeout = @configuration[:half_open_resource_timeout]
+      exponential_backoff_error_timeout = @configuration[:exponential_backoff_error_timeout]
 
       unless error_timeout.is_a?(Numeric) && error_timeout > 0
         err = "error_timeout must be a positive number, got #{error_timeout}"
@@ -174,6 +175,56 @@ module Semian
 
         raise_or_log_validation_required!(err)
       end
+
+      unless exponential_backoff_error_timeout.nil? || [true, false].include?(exponential_backoff_error_timeout)
+        err = "exponential_backoff_error_timeout must be a boolean, got #{exponential_backoff_error_timeout}"
+        err += hint_format("Use true to enable exponential backoff for error timeout. Use false to disable.")
+
+        raise_or_log_validation_required!(err)
+      end
+
+      # Validate exponential backoff initial timeout
+      exponential_backoff_initial_timeout = @configuration[:exponential_backoff_initial_timeout]
+      unless exponential_backoff_initial_timeout.nil? || (exponential_backoff_initial_timeout.is_a?(Numeric) && exponential_backoff_initial_timeout > 0)
+        err = "exponential_backoff_initial_timeout must be a positive number, got #{exponential_backoff_initial_timeout}"
+        err += hint_format("This is the initial timeout when exponential backoff is enabled. Must be less than error_timeout.")
+
+        raise_or_log_validation_required!(err)
+      end
+
+      # Validate exponential backoff multiplier
+      exponential_backoff_multiplier = @configuration[:exponential_backoff_multiplier]
+      unless exponential_backoff_multiplier.nil? || (exponential_backoff_multiplier.is_a?(Numeric) && exponential_backoff_multiplier > 1)
+        err = "exponential_backoff_multiplier must be a number greater than 1, got #{exponential_backoff_multiplier}"
+        err += hint_format("This is the factor by which the timeout increases on each subsequent opening. Common values are 2 (double) or 1.5.")
+
+        raise_or_log_validation_required!(err)
+      end
+
+      # Ensure exponential backoff parameters are only provided when exponential_backoff_error_timeout is true
+      unless exponential_backoff_error_timeout
+        if exponential_backoff_initial_timeout
+          err = "exponential_backoff_initial_timeout can only be specified when exponential_backoff_error_timeout is true"
+          err += hint_format("Set exponential_backoff_error_timeout: true to use exponential backoff features.")
+
+          raise_or_log_validation_required!(err)
+        end
+
+        if exponential_backoff_multiplier
+          err = "exponential_backoff_multiplier can only be specified when exponential_backoff_error_timeout is true"
+          err += hint_format("Set exponential_backoff_error_timeout: true to use exponential backoff features.")
+
+          raise_or_log_validation_required!(err)
+        end
+      end
+
+      # Ensure initial timeout is less than error_timeout when using exponential backoff
+      if exponential_backoff_error_timeout && exponential_backoff_initial_timeout && exponential_backoff_initial_timeout >= error_timeout
+        err = "exponential_backoff_initial_timeout (#{exponential_backoff_initial_timeout}) must be less than error_timeout (#{error_timeout})"
+        err += hint_format("The initial timeout should be smaller than the maximum timeout for exponential backoff to be effective.")
+
+        raise_or_log_validation_required!(err)
+      end
     end
 
     def validate_quota!(quota)

data/lib/semian/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Semian
-  VERSION = "0.27.0"
+  VERSION = "0.27.1"
 end

data/lib/semian.rb

@@ -197,6 +197,18 @@ 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)
+  #
   # Returns the registered resource.
   def register(name, **options)
     return UnprotectedResource.new(name) if ENV.key?("SEMIAN_DISABLED")
@@ -323,6 +335,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.27.1
 platform: ruby
 authors:
 - Scott Francis
@@ -94,7 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Bulkheading for Ruby with SysV semaphores
 test_files: []