stoplight 3.0.0 → 4.0.0

data/lib/stoplight/builder.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Stoplight
+  # An interface to build Stoplight configuration. The builder is
+  # immutable, so it's safe to pass an instance of this builder
+  # across the code.
+  #
+  # @example
+  #   circuit_breaker = Stoplight('http_api')
+  #     .with_data_store(data_store)
+  #     .with_cool_off_time(60)
+  #     .with_threshold(5)
+  #     .with_window_size(3600)
+  #     .with_notifiers(notifiers)
+  #     .with_error_notifier(error_notifier) #=> <#Stoplight::Builder ..>
+  #
+  # It's safe to pass this +circuit_breaker+ around your code like this:
+  #
+  #     def call(circuit_breaker)
+  #       circuit_breaker.run { call_api }
+  #     end
+  #
+  # @api private use +Stoplight()+ method instead
+  class Builder
+    include CircuitBreaker
+    extend Forwardable
+
+    def_delegator :build, :with_error_handler
+    def_delegator :build, :with_fallback
+    def_delegator :build, :color
+    def_delegator :build, :run
+    def_delegator :build, :lock
+    def_delegator :build, :unlock
+
+    class << self
+      # @param settings [Hash]
+      #   @see +Stoplight::Configuration#initialize+
+      # @return [Stoplight::Builder]
+      def with(**settings)
+        new Configuration.new(**settings)
+      end
+    end
+
+    # @param [Stoplight::Configuration]
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    # @return [Stoplight::Light]
+    def build(&code)
+      Light.new(configuration.name, configuration, &code)
+    end
+
+    # @param other [any]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(self.class) && configuration == other.configuration
+    end
+
+    private
+
+    def reconfigure(configuration)
+      self.class.new(configuration)
+    end
+  end
+end

data/lib/stoplight/circuit_breaker.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Stoplight
+  # @abstract
+  module CircuitBreaker
+    include Configurable
+
+    # Configures a custom proc that allows you to not to handle an error
+    # with Stoplight.
+    #
+    # @example
+    #   light = Stoplight('example')
+    #     .with_error_handler do |error, handler|
+    #       raise error if error.is_a?(ActiveRecord::RecordNotFound)
+    #       handle.call(error)
+    #     end
+    #   light.run { User.find(123) }
+    #
+    # In the example above, the +ActiveRecord::RecordNotFound+ doesn't
+    # move the circuit breaker into the red state.
+    #
+    # @yieldparam error [Exception]
+    # @yieldparam handle [Proc]
+    # @return [Stoplight::CircuitBreaker]
+    def with_error_handler(&error_handler)
+      raise NotImplementedError
+    end
+
+    # Configures light with the given fallback block
+    #
+    # @example
+    #   light = Stoplight('example')
+    #   light.with_fallback { |error| e.is_a?()ZeroDivisionError) ? 0 : nil }
+    #   light.run { 1 / 0} #=> 0
+    #
+    # @yieldparam error [Exception, nil]
+    # @return [Stoplight::CircuitBreaker]
+    def with_fallback(&fallback)
+      raise NotImplementedError
+    end
+
+    # Returns current color:
+    #   * +Stoplight::Color::GREEN+ -- circuit breaker is closed
+    #   * +Stoplight::Color::RED+ -- circuit breaker is open
+    #   * +Stoplight::Color::YELLOW+ -- circuit breaker is half-open
+    #
+    # @example
+    #   light = Stoplight('example')
+    #   light.color #=> Color::GREEN
+    #
+    # @return [String] returns current light color
+    def color
+      raise NotImplementedError
+    end
+
+    # Runs the given block of code with this circuit breaker
+    #
+    # @example
+    #   light = Stoplight('example')
+    #   light.run { 2/0 }
+    #
+    # @raise [Stoplight::Error::RedLight]
+    # @return [any]
+    def run(&code)
+      raise NotImplementedError
+    end
+
+    # Locks light in either +State::LOCKED_RED+ or +State::LOCKED_GREEN+
+    #
+    # @example
+    #   light = Stoplight('example-locked')
+    #   light.lock(Stoplight::Color::RED)
+    #
+    # @param color [String] should be either +Color::RED+ or +Color::GREEN+
+    # @return [Stoplight::CircuitBreaker] returns locked circuit breaker
+    def lock(color)
+      raise NotImplementedError
+    end
+
+    # Unlocks light and sets it's state to State::UNLOCKED
+    #
+    # @example
+    #   light = Stoplight('example-locked')
+    #   light.lock(Stoplight::Color::RED)
+    #   light.unlock
+    #
+    # @return [Stoplight::CircuitBreaker] returns unlocked circuit breaker
+    def unlock
+      raise NotImplementedError
+    end
+  end
+end

data/lib/stoplight/configurable.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Stoplight
+  # @api private
+  # @abstract include the module and define +#reconfigure+ method
+  module Configurable
+    # @!attribute [r] configuration
+    #   @return [Stoplight::Configuration]
+    #   @api private
+    attr_reader :configuration
+
+    # Configures data store to be used with this circuit breaker
+    #
+    # @example
+    #   Stoplight('example')
+    #     .with_data_store(Stoplight::DataStore::Memory.new)
+    #
+    # @param data_store [DataStore::Base]
+    # @return [Stoplight::CircuitBreaker]
+    def with_data_store(data_store)
+      reconfigure(configuration.with(data_store: data_store))
+    end
+
+    # Configures cool off time. Stoplight automatically tries to recover
+    # from the red state after the cool off time.
+    #
+    # @example
+    #   Stoplight('example')
+    #     .cool_off_time(60)
+    #
+    # @param cool_off_time [Numeric] number of seconds
+    # @return [Stoplight::CircuitBreaker]
+    def with_cool_off_time(cool_off_time)
+      reconfigure(configuration.with(cool_off_time: cool_off_time))
+    end
+
+    # Configures custom threshold. After this number of failures Stoplight
+    # switches to the red state:
+    #
+    # @example
+    #   Stoplight('example')
+    #     .with_threshold(5)
+    #
+    # @param threshold [Numeric]
+    # @return [Stoplight::CircuitBreaker]
+    def with_threshold(threshold)
+      reconfigure(configuration.with(threshold: threshold))
+    end
+
+    # Configures custom window size which Stoplight uses to count failures. For example,
+    #
+    # @example
+    #   Stoplight('example')
+    #     .with_threshold(5)
+    #     .with_window_size(60)
+    #
+    # The above example will turn to red light only when 5 errors happen
+    # within 60 seconds period.
+    #
+    # @param window_size [Numeric] number of seconds
+    # @return [Stoplight::CircuitBreaker]
+    def with_window_size(window_size)
+      reconfigure(configuration.with(window_size: window_size))
+    end
+
+    # Configures custom notifier
+    #
+    # @example
+    #   io = StringIO.new
+    #   notifier = Stoplight::Notifier::IO.new(io)
+    #   Stoplight('example')
+    #     .with_notifiers([notifier])
+    #
+    # @param notifiers [Array<Notifier::Base>]
+    # @return [Stoplight::CircuitBreaker]
+    def with_notifiers(notifiers)
+      reconfigure(configuration.with(notifiers: notifiers))
+    end
+
+    # @param error_notifier [Proc]
+    # @return [Stoplight::CircuitBreaker]
+    # @api private
+    def with_error_notifier(&error_notifier)
+      reconfigure(configuration.with(error_notifier: error_notifier))
+    end
+
+    private
+
+    # @param [Stoplight::Configuration]
+    # @return [Stoplight::CircuitBreaker]
+    def reconfigure(_configuration)
+      raise NotImplementedError, "#{self.class.name}#reconfigure is not implemented"
+    end
+  end
+end

data/lib/stoplight/configuration.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Stoplight
+  # A +Stoplight::Light+ configuration object.
+  class Configuration
+    class << self
+      alias __new_without_defaults__ new
+
+      # It overrides the +Configuration.new+ to inject default settings
+      # @see +Stoplight::Configuration#initialize+
+      def new(**settings)
+        __new_without_defaults__(
+          **default_settings.merge(settings)
+        )
+      end
+
+      private
+
+      # @return [Hash]
+      def default_settings
+        {
+          cool_off_time: Default::COOL_OFF_TIME,
+          data_store: Stoplight.default_data_store,
+          error_notifier: Stoplight.default_error_notifier,
+          notifiers: Stoplight.default_notifiers,
+          threshold: Default::THRESHOLD,
+          window_size: Default::WINDOW_SIZE
+        }
+      end
+    end
+
+    # @!attribute [r] name
+    #   @return [String]
+    attr_reader :name
+
+    # @!attribute [r] cool_off_time
+    #   @return [Numeric]
+    attr_reader :cool_off_time
+
+    # @!attribute [r] data_store
+    #   @return [Stoplight::DataStore::Base]
+    attr_reader :data_store
+
+    # @!attribute [r] error_notifier
+    #   # @return [StandardError => void]
+    attr_reader :error_notifier
+
+    # @!attribute [r] notifiers
+    #   # @return [Array<Notifier::Base>]
+    attr_reader :notifiers
+
+    # @!attribute [r] threshold
+    #   @return [Numeric]
+    attr_reader :threshold
+
+    # @!attribute [r] window_size
+    #   @return [Numeric]
+    attr_reader :window_size
+
+    # @param name [String]
+    # @param cool_off_time [Numeric]
+    # @param data_store [Stoplight::DataStore::Base]
+    # @param error_notifier [Proc]
+    # @param notifiers [Stoplight::Notifier::Base]
+    # @param threshold [Numeric]
+    # @param window_size [Numeric]
+    def initialize(name:, cool_off_time:, data_store:, error_notifier:, notifiers:, threshold:, window_size:)
+      @name = name
+      @cool_off_time = cool_off_time
+      @data_store = data_store
+      @error_notifier = error_notifier
+      @notifiers = notifiers
+      @threshold = threshold
+      @window_size = window_size
+    end
+
+    # @param other [any]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(self.class) && settings == other.settings
+    end
+
+    # @param cool_off_time [Numeric]
+    # @param data_store [Stoplight::DataStore::Base]
+    # @param error_notifier [Proc]
+    # @param name [String]
+    # @param notifiers [Stoplight::Notifier::Base]
+    # @param threshold [Numeric]
+    # @param window_size [Numeric]
+    # @return [Stoplight::Configuration]
+    def with(
+      cool_off_time: self.cool_off_time,
+      data_store: self.data_store,
+      error_notifier: self.error_notifier,
+      name: self.name,
+      notifiers: self.notifiers,
+      threshold: self.threshold,
+      window_size: self.window_size
+    )
+      Configuration.new(
+        cool_off_time: cool_off_time,
+        data_store: data_store,
+        error_notifier: error_notifier,
+        name: name,
+        notifiers: notifiers,
+        threshold: threshold,
+        window_size: window_size
+      )
+    end
+
+    protected
+
+    # @return [Hash]
+    def settings
+      {
+        cool_off_time: cool_off_time,
+        data_store: data_store,
+        error_notifier: error_notifier,
+        name: name,
+        notifiers: notifiers,
+        threshold: threshold,
+        window_size: window_size
+      }
+    end
+  end
+end

data/lib/stoplight/data_store/base.rb

@@ -52,6 +52,15 @@ module Stoplight
       def clear_state(_light)
         raise NotImplementedError
       end
+
+      # @param _light [Light]
+      # @param _from_color [String]
+      # @param _to_color [String]
+      # @yield _block
+      # @return [Void]
+      def with_notification_lock(_light, _from_color, _to_color, &_block)
+        raise NotImplementedError
+      end
     end
   end
 end

data/lib/stoplight/data_store/memory.rb

@@ -7,10 +7,12 @@ module Stoplight
     # @see Base
     class Memory < Base
       include MonitorMixin
+      KEY_SEPARATOR = ':'
 
       def initialize
         @failures = Hash.new { |h, k| h[k] = [] }
         @states = Hash.new { |h, k| h[k] = State::UNLOCKED }
+        @last_notifications = {}
         super() # MonitorMixin
       end
 
@@ -19,18 +21,23 @@ module Stoplight
       end
 
       def get_all(light)
-        synchronize { [@failures[light.name], @states[light.name]] }
+        synchronize { [query_failures(light), @states[light.name]] }
       end
 
       def get_failures(light)
-        synchronize { @failures[light.name] }
+        synchronize { query_failures(light) }
       end
 
       def record_failure(light, failure)
         synchronize do
-          n = light.threshold - 1
-          @failures[light.name] = @failures[light.name].first(n)
-          @failures[light.name].unshift(failure).size
+          light_name = light.name
+
+          # Keep at most +light.threshold+ number of errors
+          @failures[light_name] = @failures[light_name].first(light.threshold - 1)
+          @failures[light_name].unshift(failure)
+          # Remove all errors happened before the window start
+          @failures[light_name] = query_failures(light, failure.time)
+          @failures[light_name].size
         end
       end
 
@@ -49,6 +56,40 @@ module Stoplight
       def clear_state(light)
         synchronize { @states.delete(light.name) }
       end
+
+      def with_notification_lock(light, from_color, to_color)
+        synchronize do
+          if last_notification(light) != [from_color, to_color]
+            set_last_notification(light, from_color, to_color)
+
+            yield
+          end
+        end
+      end
+
+      private
+
+      # @param light [Stoplight::Light]
+      # @return [Array, nil]
+      def last_notification(light)
+        @last_notifications[light.name]
+      end
+
+      # @param light [Stoplight::Light]
+      # @param from_color [String]
+      # @param to_color [String]
+      # @return [void]
+      def set_last_notification(light, from_color, to_color)
+        @last_notifications[light.name] = [from_color, to_color]
+      end
+
+      # @param light [Stoplight::Light]
+      # @return [<Stoplight::Failure>]
+      def query_failures(light, time = Time.now)
+        @failures[light.name].select do |failure|
+          failure.time.to_i > time.to_i - light.window_size
+        end
+      end
     end
   end
 end

data/lib/stoplight/data_store/redis.rb

@@ -1,15 +1,29 @@
 # frozen_string_literal: true
 
+require 'redlock'
+
 module Stoplight
   module DataStore
+    # == Errors
+    # All errors are stored in the sorted set where keys are serialized errors and
+    # values (Redis uses "score" term) contain integer representations of the time
+    # when an error happened.
+    #
+    # This data structure enables us to query errors that happened within a specific
+    # period. We use this feature to support +window_size+ option.
+    #
+    # To avoid uncontrolled memory consumption, we keep at most +light.threshold+ number
+    # of errors happened within last +light.window_size+ seconds (by default infinity).
+    #
     # @see Base
     class Redis < Base
-      KEY_PREFIX = 'stoplight'
       KEY_SEPARATOR = ':'
+      KEY_PREFIX = %w[stoplight v4].join(KEY_SEPARATOR)
 
       # @param redis [::Redis]
-      def initialize(redis)
+      def initialize(redis, redlock: Redlock::Client.new([redis]))
         @redis = redis
+        @redlock = redlock
       end
 
       def names
@@ -40,10 +54,14 @@ module Stoplight
         normalize_failures(query_failures(light), light.error_notifier)
       end
 
+      # Saves a new failure to the errors HSet and cleans up outdated errors.
       def record_failure(light, failure)
-        size, = @redis.multi do |transaction|
-          transaction.lpush(failures_key(light), failure.to_json)
-          transaction.ltrim(failures_key(light), 0, light.threshold - 1)
+        *, size = @redis.multi do |transaction|
+          failures_key = failures_key(light)
+
+          transaction.zadd(failures_key, failure.time.to_i, failure.to_json)
+          remove_outdated_failures(light, failure.time, transaction: transaction)
+          transaction.zcard(failures_key)
         end
 
         size
@@ -76,10 +94,49 @@ module Stoplight
         normalize_state(state)
       end
 
+      LOCK_TTL = 2_000 # milliseconds
+
+      def with_notification_lock(light, from_color, to_color)
+        @redlock.lock(notification_lock_key(light), LOCK_TTL) do
+          if last_notification(light) != [from_color, to_color]
+            set_last_notification(light, from_color, to_color)
+
+            yield
+          end
+        end
+      end
+
       private
 
+      # @param light [Stoplight::Light]
+      # @param time [Time]
+      def remove_outdated_failures(light, time, transaction: @redis)
+        failures_key = failures_key(light)
+
+        # Remove all errors happened before the window start
+        transaction.zremrangebyscore(failures_key, 0, time.to_i - light.window_size)
+        # Keep at most +light.threshold+ number of errors
+        transaction.zremrangebyrank(failures_key, 0, -light.threshold - 1)
+      end
+
+      # @param light [Stoplight::Light]
+      # @return [Array, nil]
+      def last_notification(light)
+        @redis.get(last_notification_key(light))&.split('->')
+      end
+
+      # @param light [Stoplight::Light]
+      # @param from_color [String]
+      # @param to_color [String]
+      # @return [void]
+      def set_last_notification(light, from_color, to_color)
+        @redis.set(last_notification_key(light), [from_color, to_color].join('->'))
+      end
+
       def query_failures(light, transaction: @redis)
-        transaction.lrange(failures_key(light), 0, -1)
+        window_start = Time.now.to_i - light.window_size
+
+        transaction.zrange(failures_key(light), Float::INFINITY, window_start, rev: true, by_score: true)
       end
 
       def normalize_failures(failures, error_notifier)
@@ -99,10 +156,22 @@ module Stoplight
         state || State::UNLOCKED
       end
 
+      # We store a list of failures happened in the  +light+ in this key
+      #
+      # @param light [Stoplight::Light]
+      # @return [String]
       def failures_key(light)
         key('failures', light.name)
       end
 
+      def notification_lock_key(light)
+        key('notification_lock', light.name)
+      end
+
+      def last_notification_key(light)
+        key('last_notification', light.name)
+      end
+
       def states_key
         key('states')
       end

data/lib/stoplight/default.rb

@@ -23,5 +23,7 @@ module Stoplight
     ].freeze
 
     THRESHOLD = 3
+
+    WINDOW_SIZE = Float::INFINITY
   end
 end

data/lib/stoplight/error.rb

@@ -16,6 +16,7 @@ module Stoplight
     ].freeze
 
     Base = Class.new(StandardError)
+    IncorrectColor = Class.new(Base)
     RedLight = Class.new(Base)
   end
 end

data/lib/stoplight/light/deprecated.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Stoplight
+  class Light
+    # @api private
+    module Deprecated
+      def default_data_store
+        warn '[DEPRECATED] `Stoplight::Light.default_data_store` is deprecated. ' \
+          'Please use `Stoplight.default_data_store` instead.'
+        Stoplight.default_data_store
+      end
+
+      def default_data_store=(value)
+        warn '[DEPRECATED] `Stoplight::Light.default_data_store=` is deprecated. ' \
+          'Please use `Stoplight.default_data_store=` instead.'
+        Stoplight.default_data_store = value
+      end
+
+      def default_notifiers
+        warn '[DEPRECATED] `Stoplight::Light.default_notifiers` is deprecated. ' \
+          'Please use `Stoplight.default_notifiers` instead.'
+        Stoplight.default_notifiers
+      end
+
+      def default_notifiers=(value)
+        warn '[DEPRECATED] `Stoplight::Light.default_notifiers=` is deprecated. ' \
+          'Please use `Stoplight.default_notifiers=` instead.'
+        Stoplight.default_notifiers = value
+      end
+
+      def default_error_notifier
+        warn '[DEPRECATED] `Stoplight::Light.default_error_notifier` is deprecated. ' \
+          'Please use `Stoplight.default_error_notifier` instead.'
+        Stoplight.default_error_notifier
+      end
+
+      def default_error_notifier=(value)
+        warn '[DEPRECATED] `Stoplight::Light.default_error_notifier=` is deprecated. ' \
+          'Please use `Stoplight.default_error_notifier=` instead.'
+        Stoplight.default_error_notifier = value
+      end
+    end
+  end
+end