semian 0.28.3 → 0.28.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65071f9b9f241c4306a81f24e696220928dd7fd42fe50f9664f51212af37be27
-  data.tar.gz: aea78d645e703f42516e8a507887184a85ef98d547312646f609d6d145c9c2ee
+  metadata.gz: c6794eae127eb46d682ae8b1e26932eab02aa23256eec0f69b0e08302d016ef1
+  data.tar.gz: 15d40e05ef6f272bc011fa7a0da2baeefbaba9834542057c139011a213ce5c86
 SHA512:
-  metadata.gz: f628d7359a24fe78fc5ae8885f81e181d1e1a6da1b2956079fdc19e48df63d78f76de29d0cf681ea8c9e6bfc8952b23ab69e86d7313a49628c52ed6b482b49b2
-  data.tar.gz: f166272364381bdc17db8bfc6bf4b62827ae0ac7c99803b1ab6617acc80244d0163dd2a54b7f704501fd4790135fa2f7fbc90b181a8f656d05ecbff83e9bc7c6
+  metadata.gz: 71f5b87bab4fdeefc8988dd06547b62825caf44d5afaabd8308b9cafdfaf0762cf5f6cddecb309dcdb70848e925db6e76e915d0632e83bd3a1c18aed76360128
+  data.tar.gz: 1ed4d05cd272eebb88f7f7b4842d5f106ee2f58935a4662bb5cfeb0ec64503397466569b46dafaa6074981061b86c13fb25c480b1c4e703f8be90ab7018720b4

data/README.md

@@ -83,7 +83,8 @@ To create a Semian adapter you must implement the following methods:
 1. [`include Semian::Adapter`][semian-adapter]. Use the helpers to wrap the
    resource. This takes care of situations such as monitoring, nested resources,
    unsupported platforms, creating the Semian resource if it doesn't already
-   exist and so on.
+   exist and so on. Include it in an object that represents a single resource,
+   typically one connection — see [Thread Safety](#thread-safety).
 2. `#semian_identifier`. This is responsible for returning a symbol that
    represents every unique resource, for example `redis_master` or
    `mysql_shard_1`. This is usually assembled from a `name` attribute on the
@@ -192,6 +193,10 @@ if it is set to `false`, it will log misconfigured parameters verbosely in outpu
 If not specified, it will use `Semian.default_force_config_validation` as
 the flag.
 
+Resource names (strings or symbols) must not contain null bytes (`\0`). Registration
+raises `ArgumentError` regardless of `force_config_validation`, even when Semian
+is disabled. Bulkhead construction also rejects null bytes in `Semian.namespace`.
+
 ##### Migration Strategy for Force Config Validation
 
 When migrating to use `force_config_validation: true`, follow these steps:
@@ -214,6 +219,27 @@ Semian's circuit breaker implementation is thread-safe by default as of
 `v0.7.0`. If you'd like to disable it for performance reasons, pass
 `thread_safety_disabled: true` to the resource options.
 
+An adapter instance represents one resource. Once that resource has been
+acquired, Semian treats further access through the same instance as part of the
+same session: nested or overlapping calls do not re-enter the circuit breaker
+and do not take a second bulkhead ticket, so a circuit that opens elsewhere in
+the process cannot interrupt a session that is already in flight and
+succeeding. Every adapter that ships with Semian has this shape — the mixin is
+included in a connection object, and the session is that connection's unit of
+work.
+
+This is likely to give unexpected results if the adapter instance is shared
+process-wide, such as by a singleton. While any call is in flight, calls made
+through the same instance from other threads are treated as part of that
+session, so they are not fast-failed when the circuit has opened since that
+first acquire, and they cannot contribute failures. Where calls overlap
+continuously, that keeps the circuit closed while the resource is failing.
+Consider introducing a "session" object as the adapterized wrapper around the
+singleton instead, created per unit of work — per request, say. Circuit breaker
+and bulkhead state is keyed by `semian_identifier` and held in a process-wide
+registry, so short-lived adapter instances that share an identifier all share
+one circuit.
+
 Bulkheads should be disabled (pass `bulkhead: false`) in a threaded environment
 (e.g. Puma or Sidekiq), but can safely be enabled in non-threaded environments
 (e.g. Resque and Unicorn). As described in this document, circuit breakers alone
@@ -607,6 +633,76 @@ It is possible to disable Circuit Breaker with environment variable
 For more information about configuring these parameters, please read
 [this post](https://shopify.engineering/circuit-breaker-misconfigured).
 
+#### Error-Rate Circuit Breaker
+
+The circuit breaker above opens after an absolute number of errors (`error_threshold`), regardless of how many
+requests succeeded in the meantime. For a resource that is mostly healthy, such as a pool of replicas where one is
+failing, a fixed number of errors is reached sooner the more traffic a worker sends, and the circuit then fails
+*every* request instead of the few that were failing.
+
+Set **error_rate_threshold** to open the circuit when that fraction of recent requests failed instead:
+
+```ruby
+Semian.register(
+  :mysql_replicas,
+  error_rate_threshold: 0.5,    # open when 50% of requests failed...
+  minimum_request_volume: 20,   # ...out of at least 20 requests...
+  error_rate_window: 10,        # ...in the last 10 seconds
+  error_timeout: 5,
+  success_threshold: 2,
+  bulkhead: false,
+)
+```
+
+- **error_rate_threshold**. A number between 0 and 1 (exclusive): the fraction of requests in the window that must
+  have failed to open the circuit. Required to enable this circuit breaker.
+- **minimum_request_volume**. The number of requests that must have happened in the window before the error rate is
+  considered, so that 1 failure out of 1 request doesn't open the circuit. Defaults to 10.
+- **error_rate_window**. Seconds of history, rounded up to whole seconds. Defaults to 10. One-second buckets cover
+  between `error_rate_window - 1` and `error_rate_window` seconds after rounding.
+
+Invalid values for these three options raise an `ArgumentError` when the resource is registered, regardless of
+`force_config_validation`: `error_rate_threshold: 50` instead of `0.5`, for example, would otherwise leave a circuit
+that never opens. So does setting `error_rate_threshold` together with `adaptive_circuit_breaker` or
+`dual_circuit_breaker`, when the circuit breaker is enabled.
+
+`error_timeout`, `success_threshold`, `half_open_resource_timeout` and the `exponential_backoff_*` options work as
+described above. `error_threshold`, `error_threshold_timeout`, `error_threshold_timeout_enabled` and
+`lumping_interval` are replaced by the options above and are ignored.
+
+Things to know when choosing values:
+
+- A rate needs data. State is kept per worker process, so a process that sees fewer than `minimum_request_volume`
+  requests in `error_rate_window` seconds never opens the circuit, even if all of them fail. Size both options for the
+  traffic a single process sends to the resource. These are counts within the window, not averages: bursty traffic
+  with a low average rate can still reach the minimum volume.
+- After a resource starts failing completely, the circuit opens once failures make up `error_rate_threshold` of the
+  window. With steady traffic and a window full of successes, this takes about
+  `error_rate_threshold * error_rate_window` seconds, provided the minimum volume is met. Irregular traffic can take
+  longer.
+- Opening the circuit fails *all* requests until it recovers, so `error_rate_threshold` should be higher than the
+  fraction of requests you expect to fail when a part of the resource is unhealthy (for example one replica out of
+  four is 25%).
+- Successes are counted while the circuit is closed, adding a small cost to each request.
+
+Failures include configured exceptions (and `Semian::BaseError`) and adapter-reported failures, including failed
+connections and pings. Successful connections and pings (`:connection` and `:ping` scopes) are not counted in the
+error rate, nor are errors not in `exceptions`, errors for which `marks_semian_circuits?` is false, and open-circuit
+rejections. Recovery is unchanged from the circuit breaker above: in the half-open state every successful acquire,
+including a successful connection or ping, counts towards `success_threshold`.
+
+Each acquire counts at most one failure, however often it is reported with `mark_failed`: inside the block, or
+afterwards with the error that the block raised, at any later time and from any thread. The identity of the error
+object ties a report to its acquire, without modifying or retaining the error, so this also holds for frozen errors.
+Two cases are inherently ambiguous: when the same error object ends several acquires of a resource, a later report
+is attributed to the latest of them, and a copy of an error (for example one that was marshaled) is a different
+object, so reporting it counts a new failure. The `:state_change` notification and state transition log include the
+error rate at the time of the transition.
+
+The gRPC adapter observes errors raised during the protected call. For a streaming RPC that returns an enumerator of
+responses, the protected acquire ends and counts as a success when the enumerator is returned. Errors raised later
+while consuming it are not observed. This is how the adapter behaves with the circuit breaker above as well.
+
 #### Adaptive Circuit Breaker (Experimental)
 
 Semian also includes an experimental adaptive circuit breaker that uses a [PID controller](https://en.wikipedia.org/wiki/Proportional%E2%80%93integral%E2%80%93derivative_controller)

data/ext/semian/resource.c

@@ -332,18 +332,17 @@ check_tickets_arg(VALUE tickets)
 static const char*
 check_id_arg(VALUE id)
 {
-  const char *c_id_str = NULL;
-
   if (TYPE(id) != T_SYMBOL && TYPE(id) != T_STRING) {
     rb_raise(rb_eTypeError, "id must be a symbol or string");
   }
   if (TYPE(id) == T_SYMBOL) {
-    c_id_str = rb_id2name(rb_to_id(id));
-  } else if (TYPE(id) == T_STRING) {
-    c_id_str = RSTRING_PTR(id);
+    id = rb_sym2str(id);
+  }
+  if (memchr(RSTRING_PTR(id), '\0', RSTRING_LEN(id)) != NULL) {
+    rb_raise(rb_eArgError, "name must not contain null bytes");
   }
 
-  return c_id_str;
+  return StringValueCStr(id);
 }
 
 static double

data/lib/semian/adapter.rb

@@ -79,11 +79,10 @@ module Semian
     end
 
     def mark_resource_as_acquired
-      previous = @resource_acquired
       @resource_acquired = true
       yield
     ensure
-      @resource_acquired = previous
+      @resource_acquired = false
     end
   end
 end

data/lib/semian/circuit_breaker.rb

@@ -110,6 +110,10 @@ module Semian
     def transition_to_close(scope: nil, adapter: nil)
       notify_state_transition(:closed, scope: scope, adapter: adapter)
       log_state_transition(:closed)
+      close_state
+    end
+
+    def close_state
       @state.close!
       @errors.clear
       # Reset exponential backoff when circuit closes
@@ -119,6 +123,10 @@ module Semian
     def transition_to_open(scope: nil, adapter: nil)
       notify_state_transition(:open, scope: scope, adapter: adapter)
       log_state_transition(:open)
+      open_state
+    end
+
+    def open_state
       @state.open!
     end
 
@@ -165,9 +173,9 @@ module Semian
       return if @state.nil? || new_state == @state.value
 
       str = "[#{self.class.name}] State transition from #{@state.value} to #{new_state}."
-      str += " success_count=#{@successes.value} error_count=#{@errors.size}"
+      str += " success_count=#{@successes.value}#{observed_errors_log}"
       str += " success_count_threshold=#{@success_count_threshold}"
-      str += " error_count_threshold=#{@error_count_threshold}"
+      str += error_threshold_log
       str += " error_timeout=#{@error_timeout} error_last_at=\"#{@errors.last}\""
       if @exponential_backoff_error_timeout
         str += " current_error_timeout=#{@current_error_timeout}"
@@ -180,6 +188,14 @@ module Semian
       Semian.logger.info(str)
     end
 
+    def observed_errors_log
+      " error_count=#{@errors.size}"
+    end
+
+    def error_threshold_log
+      " error_count_threshold=#{@error_count_threshold}"
+    end
+
     def notify_state_transition(new_state, scope: nil, adapter: nil)
       Semian.notify(:state_change, self, scope, adapter, state: new_state)
     end

data/lib/semian/configuration_validator.rb

@@ -66,6 +66,7 @@ module Semian
     def validate_circuit_breaker_configuration!
       return if ENV.key?("SEMIAN_CIRCUIT_BREAKER_DISABLED")
       return unless @configuration.fetch(:circuit_breaker, true)
+      return validate_error_rate_configuration! unless @configuration[:error_rate_threshold].nil?
       return if @configuration[:adaptive_circuit_breaker] # Skip traditional validation if using adaptive
 
       require_keys!([:success_threshold, :error_threshold, :error_timeout], @configuration)
@@ -74,8 +75,12 @@ module Semian
     end
 
     def validate_thresholds!
+      validate_success_threshold!
+      validate_error_threshold!
+    end
+
+    def validate_success_threshold!
       success_threshold = @configuration[:success_threshold]
-      error_threshold = @configuration[:error_threshold]
 
       unless success_threshold.is_a?(Integer) && success_threshold > 0
         err = "success_threshold must be a positive integer, got #{success_threshold}"
@@ -86,6 +91,10 @@ module Semian
 
         raise_or_log_validation_required!(err)
       end
+    end
+
+    def validate_error_threshold!
+      error_threshold = @configuration[:error_threshold]
 
       unless error_threshold.is_a?(Integer) && error_threshold > 0
         err = "error_threshold must be a positive integer, got #{error_threshold}"
@@ -98,11 +107,52 @@ module Semian
       end
     end
 
-    def validate_timeouts!
+    def validate_error_rate_configuration!
+      if @configuration[:adaptive_circuit_breaker] || @configuration[:dual_circuit_breaker]
+        raise_invalid_error_rate_option!("error_rate_threshold is not supported with adaptive_circuit_breaker or dual_circuit_breaker")
+      end
+
+      require_keys!([:success_threshold, :error_timeout], @configuration)
+      validate_success_threshold!
+      validate_timeouts!(rate_mode: true)
+
+      error_rate_threshold = @configuration[:error_rate_threshold]
+      unless error_rate_threshold.is_a?(Numeric) && error_rate_threshold.real? && error_rate_threshold.finite? && error_rate_threshold > 0 && error_rate_threshold < 1
+        raise_invalid_error_rate_option!(
+          "error_rate_threshold must be a number between 0 and 1 (exclusive), got #{error_rate_threshold}" +
+            hint_format("It is the fraction of requests that must fail, e.g. 0.5 for 50%."),
+        )
+      end
+
+      minimum_request_volume = @configuration[:minimum_request_volume]
+      unless minimum_request_volume.nil? || (minimum_request_volume.is_a?(Integer) && minimum_request_volume > 0)
+        raise_invalid_error_rate_option!("minimum_request_volume must be a positive integer, got #{minimum_request_volume}")
+      end
+
+      error_rate_window = @configuration[:error_rate_window]
+      unless error_rate_window.nil? || (error_rate_window.is_a?(Numeric) && error_rate_window.real? && error_rate_window.finite? && error_rate_window > 0)
+        raise_invalid_error_rate_option!("error_rate_window must be a positive number, got #{error_rate_window}")
+      end
+
+      ignored = [:error_threshold, :error_threshold_timeout, :error_threshold_timeout_enabled, :lumping_interval]
+        .reject { |key| @configuration[key].nil? }
+      unless ignored.empty?
+        raise_or_log_validation_required!("#{ignored.join(", ")} ignored when error_rate_threshold is set")
+      end
+    end
+
+    # These options are new, so no configuration relies on a warning: 50 instead of 0.5 would otherwise leave a circuit
+    # that can never open.
+    def raise_invalid_error_rate_option!(message)
+      raise ArgumentError, "Semian Resource #{@name}: #{message}"
+    end
+
+    def validate_timeouts!(rate_mode: false)
       error_timeout = @configuration[:error_timeout]
-      error_threshold_timeout_enabled = @configuration[:error_threshold_timeout_enabled].nil? ? true : @configuration[:error_threshold_timeout_enabled]
-      error_threshold = @configuration[:error_threshold]
-      lumping_interval = @configuration[:lumping_interval]
+      legacy = rate_mode ? {} : @configuration
+      error_threshold_timeout_enabled = legacy[:error_threshold_timeout_enabled].nil? ? true : legacy[:error_threshold_timeout_enabled]
+      error_threshold = legacy[:error_threshold]
+      lumping_interval = legacy[:lumping_interval]
       half_open_resource_timeout = @configuration[:half_open_resource_timeout]
       exponential_backoff_error_timeout = @configuration[:exponential_backoff_error_timeout]
 
@@ -117,16 +167,16 @@ module Semian
       end
 
       # This state checks for contradictions between error_threshold_timeout_enabled and error_threshold_timeout.
-      unless error_threshold_timeout_enabled || !@configuration[:error_threshold_timeout]
-        err = "error_threshold_timeout_enabled and error_threshold_timeout must not contradict each other, got error_threshold_timeout_enabled: #{error_threshold_timeout_enabled}, error_threshold_timeout: #{@configuration[:error_threshold_timeout]}"
-        err += hint_format("Are you sure this is what you want? This will set error_threshold_timeout_enabled to #{error_threshold_timeout_enabled} while error_threshold_timeout is #{@configuration[:error_threshold_timeout] ? "truthy" : "falsy"}")
+      unless error_threshold_timeout_enabled || !legacy[:error_threshold_timeout]
+        err = "error_threshold_timeout_enabled and error_threshold_timeout must not contradict each other, got error_threshold_timeout_enabled: #{error_threshold_timeout_enabled}, error_threshold_timeout: #{legacy[:error_threshold_timeout]}"
+        err += hint_format("Are you sure this is what you want? This will set error_threshold_timeout_enabled to #{error_threshold_timeout_enabled} while error_threshold_timeout is #{legacy[:error_threshold_timeout] ? "truthy" : "falsy"}")
 
         raise_or_log_validation_required!(err)
       end
 
       # Only set this after we have checked the error_threshold_timeout_enabled condition
-      error_threshold_timeout = @configuration[:error_threshold_timeout] || error_timeout
-      unless error_threshold_timeout.is_a?(Numeric) && error_threshold_timeout > 0
+      error_threshold_timeout = legacy[:error_threshold_timeout] || error_timeout
+      unless rate_mode || (error_threshold_timeout.is_a?(Numeric) && error_threshold_timeout > 0)
         err = "error_threshold_timeout must be a positive number, got #{error_threshold_timeout}"
 
         if error_threshold_timeout == 0

data/lib/semian/error_rate_circuit_breaker.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative "circuit_breaker"
+
+module Semian
+  class ErrorRateCircuitBreaker < CircuitBreaker # :nodoc:
+    NON_REQUEST_SCOPES = [:connection, :ping].freeze
+    # Fiber-local: the innermost running acquire, as [breaker, failure counted?, enclosing acquire, success deferred?].
+    ACQUISITION = :semian_error_rate_acquisition
+    TRIP_RATE = :semian_error_rate_trip_rate
+
+    attr_reader :error_rate_threshold, :minimum_request_volume
+
+    def initialize(name, error_rate_threshold:, implementation:, minimum_request_volume: 10, error_rate_window: 10,
+      **options)
+      @error_rate_threshold = error_rate_threshold
+      @minimum_request_volume = minimum_request_volume
+      @outcomes = implementation::TimeBucketedCounter.new(window: error_rate_window)
+      # Error that ended an acquire => did that acquire (the last one it ended) count a failure? Keyed by identity,
+      # so errors are neither modified nor retained. The values are immediates, which a WeakMap never drops.
+      @ended_acquisitions = ObjectSpace::WeakMap.new
+      @reports = Mutex.new
+
+      # error_threshold only sizes the parent's last-error window, which we use for error_timeout.
+      super(name, error_threshold: 1, implementation: implementation, **options)
+    end
+
+    def acquire(resource = nil, scope: nil, adapter: nil, &block)
+      previous = Thread.current[ACQUISITION]
+      frame = Thread.current[ACQUISITION] = [self, false, previous]
+      transition_to_half_open(scope: scope, adapter: adapter) if transition_to_half_open?
+      raise OpenCircuitError unless request_allowed?
+
+      begin
+        result = maybe_with_half_open_resource_timeout(resource, &block)
+      rescue Exception => error # rubocop:disable Lint/RescueException -- adapters can report any raised exception after acquire unwinds
+        marks = @exceptions.any? { |exception| exception === error } && # rubocop:disable Style/CaseEquality -- as rescue matches
+          (!error.respond_to?(:marks_semian_circuits?) || error.marks_semian_circuits?)
+        @reports.synchronize do
+          @ended_acquisitions[error] = frame[1]
+          # Claimed below through the error; reports of other errors while that one is notified find it taken.
+          frame[1] = true if marks
+        end
+        mark_failed(error, scope: scope, adapter: adapter) if marks
+        raise
+      else
+        mark_success(scope: scope, adapter: adapter)
+      end
+      result
+    ensure
+      Thread.current[ACQUISITION] = previous
+    end
+
+    # A failure reported with the error that ended an acquire of this breaker belongs to that acquire, whenever and
+    # wherever it is reported. Any other report belongs to the innermost running acquire of this breaker in this
+    # fiber, if there is one. Each acquire counts at most one failure.
+    def mark_failed(error, scope: nil, adapter: nil)
+      return if already_counted?(error)
+
+      # A report made while another transition of this fiber is being notified must not disturb that one's rate.
+      previous_rate = Thread.current[TRIP_RATE]
+      begin
+        Thread.current[TRIP_RATE] = nil
+        @outcomes.record_failure
+        super
+      ensure
+        Thread.current[TRIP_RATE] = previous_rate
+      end
+    end
+
+    def mark_success(scope: nil, adapter: nil)
+      frame = Thread.current[ACQUISITION]
+      neutral = (frame && frame[0].equal?(self) && (frame[1] || frame[3])) || NON_REQUEST_SCOPES.include?(scope)
+      @outcomes.record_success unless neutral
+      super
+    end
+
+    class << self
+      # Identifies the innermost acquire that is running in this fiber, of any rate-based breaker.
+      def acquisition
+        Thread.current[ACQUISITION]
+      end
+
+      # An acquire that started after `since` was taken and is still running only admitted work whose outcome a later
+      # acquire records, so its success is neutral in the rate; a failure still counts. It remains a half-open
+      # success, as a successful connection is. Comparing acquires rather than asking the caller whether it acquired
+      # leaves nothing to go stale: no new acquire means nothing is deferred.
+      def defer_outcome(since:)
+        frame = Thread.current[ACQUISITION]
+        frame[3] = true if frame && !frame.equal?(since)
+      end
+    end
+
+    def destroy
+      @outcomes.destroy
+      super
+    end
+
+    def error_rate
+      successes, failures = @outcomes.counts
+      total = successes + failures
+      total.zero? ? 0.0 : failures.fdiv(total)
+    end
+
+    private
+
+    # Atomically claims the failure of the acquire that the report belongs to; concurrent reports cannot both win.
+    def already_counted?(error)
+      @reports.synchronize do
+        if @ended_acquisitions.key?(error)
+          return true if @ended_acquisitions[error]
+
+          @ended_acquisitions[error] = true
+        elsif (frame = running_acquisition)
+          return true if frame[1]
+
+          frame[1] = true
+        end
+        false
+      end
+    end
+
+    def running_acquisition
+      frame = Thread.current[ACQUISITION]
+      frame = frame[2] while frame && !frame[0].equal?(self)
+      frame
+    end
+
+    def error_threshold_reached?
+      successes, failures = @outcomes.counts
+      total = successes + failures
+      return false if total < @minimum_request_volume
+
+      rate = failures.fdiv(total)
+      return false if rate < @error_rate_threshold
+
+      Thread.current[TRIP_RATE] = [self, rate]
+      true
+    end
+
+    # Outcomes recorded before the circuit closes are forgotten and those recorded after are kept, even when they
+    # are recorded while it closes.
+    def close_state
+      @outcomes.clear { super }
+    end
+
+    # A close that finished while this failure was being notified forgot when the last error happened; without it the
+    # circuit would stay open forever.
+    def open_state
+      @outcomes.synchronize do
+        @errors << Process.clock_gettime(Process::CLOCK_MONOTONIC) if @errors.empty?
+        super
+      end
+    end
+
+    def transition_error_rate
+      trip = Thread.current[TRIP_RATE]
+      trip && trip[0].equal?(self) ? trip[1] : error_rate
+    end
+
+    def notify_state_transition(new_state, scope: nil, adapter: nil)
+      Semian.notify(:state_change, self, scope, adapter, state: new_state, error_rate: transition_error_rate)
+    end
+
+    def observed_errors_log
+      " error_rate=#{transition_error_rate.round(4)}"
+    end
+
+    def error_threshold_log
+      " error_rate_threshold=#{@error_rate_threshold} minimum_request_volume=#{@minimum_request_volume}"
+    end
+  end
+end

data/lib/semian/grpc.rb

@@ -108,9 +108,15 @@ module Semian
     end
 
     def acquire_semian_resource_grpc(scope:)
+      enclosing = ErrorRateCircuitBreaker.acquisition
       acquire_semian_resource(adapter: :grpc, scope: scope) do
         result = yield
-        handle_operation(result, scope) if result.is_a?(::GRPC::ActiveCall::Operation)
+        if result.is_a?(::GRPC::ActiveCall::Operation)
+          handle_operation(result, scope)
+          # Creating the operation ran no RPC: only its execution is an outcome for a rate-based breaker. A nested
+          # call acquired nothing, so it defers nothing.
+          ErrorRateCircuitBreaker.defer_outcome(since: enclosing)
+        end
         result
       end
     end

data/lib/semian/resource.rb

@@ -21,6 +21,8 @@ module Semian
       unless name.is_a?(String) || name.is_a?(Symbol)
         raise TypeError, "name must be a string or symbol, got: #{name.class}"
       end
+      raise ArgumentError, "name must not contain null bytes" if name.to_s.b.include?("\0")
+      raise ArgumentError, "namespace must not contain null bytes" if Semian.namespace.to_s.b.include?("\0")
 
       if Semian.semaphores_enabled?
         if respond_to?(:initialize_semaphore)

data/lib/semian/simple_time_bucketed_counter.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Semian
+  module Simple
+    # Counts successes and failures over a trailing window, one bucket per second, oldest first.
+    # The window covers between `window - 1` and `window` seconds of history.
+    # Totals are kept next to the buckets, so recording and reading cost the same whatever the window.
+    class TimeBucketedCounter # :nodoc:
+      def initialize(window:)
+        @size = window.ceil
+        clear
+      end
+
+      def record_success
+        advance
+        @successes[-1] += 1
+        @total_successes += 1
+      end
+
+      def record_failure
+        advance
+        @failures[-1] += 1
+        @total_failures += 1
+      end
+
+      def counts
+        advance
+        [@total_successes, @total_failures]
+      end
+
+      # Clears after running the block; a thread-safe counter records nothing in between.
+      def clear
+        yield if block_given?
+        @successes = Array.new(@size, 0)
+        @failures = Array.new(@size, 0)
+        @total_successes = @total_failures = 0
+        @epoch = current_second
+        self
+      end
+
+      def synchronize
+        yield
+      end
+
+      def destroy
+        clear
+      end
+
+      private
+
+      # Once per second at most, the buckets that left the window become its newest, empty ones. That touches every
+      # bucket, but in C and whatever the gap, so the first call after an idle period stays cheap. A clock that goes
+      # backwards keeps recording into the newest bucket.
+      def advance
+        now = current_second
+        return if now <= @epoch
+
+        elapsed = [now - @epoch, @size].min
+        @total_successes = @successes.rotate!(elapsed).fill(0, -elapsed).sum
+        @total_failures = @failures.rotate!(elapsed).fill(0, -elapsed).sum
+        @epoch = now
+      end
+
+      def current_second
+        Process.clock_gettime(Process::CLOCK_MONOTONIC).to_i
+      end
+    end
+  end
+
+  module ThreadSafe
+    class TimeBucketedCounter < Simple::TimeBucketedCounter
+      def initialize(**)
+        @lock = Mutex.new
+        super
+      end
+
+      def record_success
+        @lock.synchronize { super }
+      end
+
+      def record_failure
+        @lock.synchronize { super }
+      end
+
+      def counts
+        @lock.synchronize { super }
+      end
+
+      def clear(&block)
+        @lock.synchronize { super }
+      end
+
+      def synchronize(&block)
+        @lock.synchronize(&block)
+      end
+    end
+  end
+end

data/lib/semian/version.rb

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

data/lib/semian.rb

@@ -11,11 +11,13 @@ require "semian/instrumentable"
 require "semian/platform"
 require "semian/resource"
 require "semian/circuit_breaker"
+require "semian/error_rate_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"
+require "semian/simple_time_bucketed_counter"
 require "semian/simple_integer"
 require "semian/simple_state"
 require "semian/lru_hash"
@@ -199,6 +201,18 @@ module Semian
   # +exceptions+: An array of exception classes that should be accounted as resource errors. Default [].
   # (circuit breaker)
   #
+  # +error_rate_threshold+: Open the circuit when this fraction (between 0 and 1, exclusive) of the requests in the
+  # last +error_rate_window+ seconds failed. Replaces +error_threshold+, +error_threshold_timeout+,
+  # +error_threshold_timeout_enabled+ and +lumping_interval+, which are ignored when it is set. Successes are tracked
+  # while closed. Not supported with the adaptive or dual circuit breakers. An invalid value for this option,
+  # +minimum_request_volume+ or +error_rate_window+ raises ArgumentError regardless of +force_config_validation+.
+  # (circuit breaker)
+  #
+  # +minimum_request_volume+: The number of requests that must have happened in the window before the error rate is
+  # considered. Default 10. (error_rate_threshold)
+  #
+  # +error_rate_window+: Seconds of history, rounded up to whole seconds. Default 10. (error_rate_threshold)
+  #
   #   # +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.
@@ -227,6 +241,8 @@ module Semian
   #
   # Returns the registered resource.
   def register(name, **options)
+    raise ArgumentError, "name must not contain null bytes" if name.to_s.b.include?("\0")
+
     return UnprotectedResource.new(name) if ENV.key?("SEMIAN_DISABLED")
 
     # Validate configuration before proceeding
@@ -374,6 +390,7 @@ module Semian
   def create_circuit_breaker(name, is_child: false, **options)
     return if ENV.key?("SEMIAN_CIRCUIT_BREAKER_DISABLED")
     return unless options.fetch(:circuit_breaker, true)
+    return create_error_rate_circuit_breaker(name, **options) if !options[:error_rate_threshold].nil? && !is_child
 
     exceptions = options[:exceptions] || []
     cls = is_child ? DualCircuitBreaker::ChildClassicCircuitBreaker : CircuitBreaker
@@ -402,6 +419,25 @@ module Semian
     )
   end
 
+  def create_error_rate_circuit_breaker(name, **options)
+    ErrorRateCircuitBreaker.new(
+      name,
+      exceptions: Array(options[:exceptions]) + [::Semian::BaseError],
+      implementation: implementation(**options),
+      **options.slice(
+        :error_rate_threshold,
+        :minimum_request_volume,
+        :error_rate_window,
+        :success_threshold,
+        :error_timeout,
+        :half_open_resource_timeout,
+        :exponential_backoff_error_timeout,
+        :exponential_backoff_initial_timeout,
+        :exponential_backoff_multiplier,
+      ).compact,
+    )
+  end
+
   def implementation(**options)
     # thread_safety_disabled will be replaced by a global setting
     # Semian is thread safe by default. It is possible

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: semian
 version: !ruby/object:Gem::Version
-  version: 0.28.3
+  version: 0.28.5
 platform: ruby
 authors:
 - Scott Francis
@@ -56,6 +56,7 @@ files:
 - lib/semian/circuit_breaker_behaviour.rb
 - lib/semian/configuration_validator.rb
 - lib/semian/dual_circuit_breaker.rb
+- lib/semian/error_rate_circuit_breaker.rb
 - lib/semian/grpc.rb
 - lib/semian/instrumentable.rb
 - lib/semian/lru_hash.rb
@@ -74,6 +75,7 @@ files:
 - lib/semian/simple_integer.rb
 - lib/semian/simple_sliding_window.rb
 - lib/semian/simple_state.rb
+- lib/semian/simple_time_bucketed_counter.rb
 - lib/semian/unprotected_resource.rb
 - lib/semian/version.rb
 homepage: https://github.com/shopify/semian
@@ -100,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 4.0.23
 specification_version: 4
 summary: Bulkheading for Ruby with SysV semaphores
 test_files: []