stoplight 3.0.0 → 4.0.0

data/lib/stoplight/light/lockable.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Stoplight
+  class Light
+    # The Lockable module implements the behavior of locking and unlocking the light.
+    # Light can be locked in either a State::LOCKED_RED or State::LOCKED_GREEN state.
+    # By locking the light, you force it always to run code with the chosen light color.
+    #
+    # @example
+    #   light = Stoplight('example-locked') { true }
+    #   # => #<Stoplight::Light:..>
+    #   light.run
+    #   # => true
+    #   light.lock(Stoplight::Color::RED)
+    #   # => #<Stoplight::Light:..>
+    #   light.run
+    #   # => Stoplight::Error::RedLight: example-locked
+    #   light.unlock
+    #   # => #<Stoplight::Light:..>
+    #   light.run
+    #   # => true
+    module Lockable
+      # @param color [String] should be either Color::RED or Color::GREEN
+      # @return [Stoplight::Light] returns locked light
+      def lock(color)
+        state = case color
+                when Color::RED then State::LOCKED_RED
+                when Color::GREEN then State::LOCKED_GREEN
+                else raise Error::IncorrectColor
+                end
+
+        safely { data_store.set_state(self, state) }
+
+        self
+      end
+
+      # @return [Stoplight::Light] returns unlocked light
+      def unlock
+        safely { data_store.set_state(self, Stoplight::State::UNLOCKED) }
+
+        self
+      end
+    end
+  end
+end

data/lib/stoplight/light/runnable.rb

@@ -13,33 +13,51 @@ module Stoplight
         elsif failures.size < threshold then Color::GREEN
         elsif failure && Time.now - failure.time >= cool_off_time
           Color::YELLOW
-        else Color::RED
+        else
+          Color::RED
         end
       end
 
       # @raise [Error::RedLight]
-      def run
+      def run(&code)
+        code = validate_code(&code)
         case color
-        when Color::GREEN then run_green
-        when Color::YELLOW then run_yellow
+        when Color::GREEN then run_green(&code)
+        when Color::YELLOW then run_yellow(&code)
         else run_red
         end
       end
 
       private
 
-      def run_green
+      def validate_code(&code)
+        raise ArgumentError, <<~ERROR if block_given? && self.code
+          passing code block into both `Light.new` and `Light#run` is not allowed
+        ERROR
+
+        raise ArgumentError, <<~ERROR unless block_given? || self.code
+          nothing to run. Please, pass a block into `Light#run`
+        ERROR
+
+        code || self.code
+      end
+
+      def run_green(&code)
         on_failure = lambda do |size, error|
-          notify(Color::GREEN, Color::RED, error) if size == threshold
+          notify(Color::GREEN, Color::RED, error) if failures_threshold_breached?(size, threshold)
         end
-        run_code(nil, on_failure)
+        run_code(nil, on_failure, &code)
       end
 
-      def run_yellow
+      def failures_threshold_breached?(current_failures_count, max_errors_threshold)
+        current_failures_count == max_errors_threshold
+      end
+
+      def run_yellow(&code)
         on_success = lambda do |failures|
           notify(Color::RED, Color::GREEN) unless failures.empty?
         end
-        run_code(on_success, nil)
+        run_code(on_success, nil, &code)
       end
 
       def run_red
@@ -48,7 +66,7 @@ module Stoplight
         fallback.call(nil)
       end
 
-      def run_code(on_success, on_failure)
+      def run_code(on_success, on_failure, &code)
         result = code.call
         failures = clear_failures
         on_success&.call(failures)
@@ -75,8 +93,10 @@ module Stoplight
       end
 
       def notify(from_color, to_color, error = nil)
-        notifiers.each do |notifier|
-          safely { notifier.notify(self, from_color, to_color, error) }
+        data_store.with_notification_lock(self, from_color, to_color) do
+          notifiers.each do |notifier|
+            safely { notifier.notify(self, from_color, to_color, error) }
+          end
         end
       end
 
@@ -88,15 +108,13 @@ module Stoplight
       def safely(default = nil, &code)
         return yield if data_store == Default::DATA_STORE
 
-        self
-          .class
-          .new("#{name}-safely", &code)
+        Stoplight("#{name}-safely")
           .with_data_store(Default::DATA_STORE)
           .with_fallback do |error|
             error_notifier.call(error) if error
             default
           end
-          .run
+          .run(&code)
       end
     end
   end

data/lib/stoplight/light.rb

@@ -1,103 +1,109 @@
 # frozen_string_literal: true
 
+require 'stoplight/light/deprecated'
+
 module Stoplight
-  class Light # rubocop:disable Style/Documentation
+  #
+  # @api private use +Stoplight()+ method instead
+  class Light
+    extend Forwardable
+    extend Deprecated
+    include CircuitBreaker
+    include Lockable
     include Runnable
 
+    # @!attribute [r] data_store
+    #   @return [Stoplight::DataStore::Base]
+    def_delegator :configuration, :data_store
+
+    # @!attribute [r] threshold
+    #   @return [Integer]
+    def_delegator :configuration, :threshold
+
+    # @!attribute [r] cool_off_time
+    #   @return [Fixnum]
+    def_delegator :configuration, :cool_off_time
+
+    # @!attribute [r] window_size
+    #   @return [Float]
+    def_delegator :configuration, :window_size
+
+    # @!attribute [r] notifiers
+    #   # @return [Array<Notifier::Base>]
+    def_delegator :configuration, :notifiers
+
+    # @!attribute [r] error_notifier
+    #   # @return [Proc]
+    def_delegator :configuration, :error_notifier
+
+    # @return [String]
+    attr_reader :name
     # @return [Proc]
     attr_reader :code
-    # @return [Float]
-    attr_reader :cool_off_time
-    # @return [DataStore::Base]
-    attr_reader :data_store
     # @return [Proc]
     attr_reader :error_handler
-    # @return [Proc]
-    attr_reader :error_notifier
     # @return [Proc, nil]
     attr_reader :fallback
-    # @return [String]
-    attr_reader :name
-    # @return [Array<Notifier::Base>]
-    attr_reader :notifiers
-    # @return [Fixnum]
-    attr_reader :threshold
+    # @return [Stoplight::Configuration]
+    # @api private
+    attr_reader :configuration
 
     class << self
-      # @return [DataStore::Base]
-      attr_accessor :default_data_store
-      # @return [Proc]
-      attr_accessor :default_error_notifier
-      # @return [Array<Notifier::Base>]
-      attr_accessor :default_notifiers
-    end
+      alias __new_with_configuration__ new
 
-    @default_data_store = Default::DATA_STORE
-    @default_error_notifier = Default::ERROR_NOTIFIER
-    @default_notifiers = Default::NOTIFIERS
+      # It overrides the +Light.new+ method to support an old and a new
+      # way of instantiation.
+      #
+      # @overload new(name, &code)
+      #   @param name [String]
+      #   @return [Stoplight::Light]
+      #
+      # @overload new(name, configuration)
+      #   @param name [String]
+      #   @param configuration [Stoplight::Configuration]
+      #   @return [Stoplight::Light]
+      #
+      def new(name, configuration = nil, &code)
+        if configuration
+          __new_with_configuration__(name, configuration, &code)
+        else
+          warn '[DEPRECATED] Instantiating `Stoplight::Light` is deprecated. ' \
+            'Please use `Stoplight()` method instead.'
+          Builder.with(name: name).build(&code)
+        end
+      end
+    end
 
     # @param name [String]
+    # @param configuration [Stoplight::Configuration]
     # @yield []
-    def initialize(name, &code)
+    def initialize(name, configuration, &code)
+      @configuration = configuration
       @name = name
       @code = code
-
-      @cool_off_time = Default::COOL_OFF_TIME
-      @data_store = self.class.default_data_store
       @error_handler = Default::ERROR_HANDLER
-      @error_notifier = self.class.default_error_notifier
       @fallback = Default::FALLBACK
-      @notifiers = self.class.default_notifiers
-      @threshold = Default::THRESHOLD
-    end
-
-    # @param cool_off_time [Float]
-    # @return [self]
-    def with_cool_off_time(cool_off_time)
-      @cool_off_time = cool_off_time
-      self
-    end
-
-    # @param data_store [DataStore::Base]
-    # @return [self]
-    def with_data_store(data_store)
-      @data_store = data_store
-      self
     end
 
     # @yieldparam error [Exception]
     # @yieldparam handle [Proc]
-    # @return [self]
+    # @return [Stoplight::CircuitBreaker]
     def with_error_handler(&error_handler)
       @error_handler = error_handler
       self
     end
 
-    # @yieldparam error [Exception]
-    # @return [self]
-    def with_error_notifier(&error_notifier)
-      @error_notifier = error_notifier
-      self
-    end
-
     # @yieldparam error [Exception, nil]
-    # @return [self]
+    # @return [Stoplight::CircuitBreaker]
     def with_fallback(&fallback)
       @fallback = fallback
       self
     end
 
-    # @param notifiers [Array<Notifier::Base>]
-    # @return [self]
-    def with_notifiers(notifiers)
-      @notifiers = notifiers
-      self
-    end
+    private
 
-    # @param threshold [Fixnum]
-    # @return [self]
-    def with_threshold(threshold)
-      @threshold = threshold
+    def reconfigure(configuration)
+      @configuration = configuration
       self
     end
   end

data/lib/stoplight/rspec/generic_notifier.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples 'a generic notifier' do
+  it 'includes Generic' do
+    expect(described_class).to include(Stoplight::Notifier::Generic)
+  end
+
+  describe '#formatter' do
+    it 'is initially the default' do
+      formatter = nil
+      expect(described_class.new(nil, formatter).formatter)
+        .to eql(Stoplight::Default::FORMATTER)
+    end
+
+    it 'reads the formatter' do
+      formatter = proc {}
+      expect(described_class.new(nil, formatter).formatter)
+        .to eql(formatter)
+    end
+  end
+
+  describe '#notify' do
+    let(:light) { Stoplight::Light.new(name, &code) }
+    let(:name) { ('a'..'z').to_a.shuffle.join }
+    let(:code) { -> {} }
+    let(:from_color) { Stoplight::Color::GREEN }
+    let(:to_color) { Stoplight::Color::RED }
+    let(:notifier) { described_class.new(double.as_null_object) }
+
+    it 'returns the message' do
+      error = nil
+      expect(notifier.notify(light, from_color, to_color, error))
+        .to eql(notifier.formatter.call(light, from_color, to_color, error))
+    end
+
+    it 'returns the message with an error' do
+      error = ZeroDivisionError.new('divided by 0')
+      expect(notifier.notify(light, from_color, to_color, error))
+        .to eql(notifier.formatter.call(light, from_color, to_color, error))
+    end
+  end
+end

data/lib/stoplight/rspec.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'stoplight/rspec/generic_notifier'

data/lib/stoplight/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stoplight
-  VERSION = Gem::Version.new('3.0.0')
+  VERSION = Gem::Version.new('4.0.0')
 end

data/lib/stoplight.rb

@@ -1,6 +1,19 @@
 # frozen_string_literal: true
 
 module Stoplight # rubocop:disable Style/Documentation
+  class << self
+    # @!attribute default_data_store
+    #   @return [DataStore::Base]
+    attr_accessor :default_data_store
+
+    # @!attribute default_notifiers
+    #   @return [Array<Notifier::Base>]
+    attr_accessor :default_notifiers
+
+    # @!attribute default_error_notifier
+    #   @return [Proc]
+    attr_accessor :default_error_notifier
+  end
 end
 
 require 'stoplight/version'
@@ -19,22 +32,32 @@ require 'stoplight/notifier'
 require 'stoplight/notifier/base'
 require 'stoplight/notifier/generic'
 
-require 'stoplight/notifier/bugsnag'
-require 'stoplight/notifier/hip_chat'
-require 'stoplight/notifier/honeybadger'
 require 'stoplight/notifier/io'
 require 'stoplight/notifier/logger'
-require 'stoplight/notifier/pagerduty'
-require 'stoplight/notifier/raven'
-require 'stoplight/notifier/rollbar'
-require 'stoplight/notifier/slack'
 
 require 'stoplight/default'
 
+module Stoplight # rubocop:disable Style/Documentation
+  @default_data_store = Default::DATA_STORE
+  @default_notifiers = Default::NOTIFIERS
+  @default_error_notifier = Default::ERROR_NOTIFIER
+end
+
+require 'stoplight/configurable'
+require 'stoplight/circuit_breaker'
+require 'stoplight/builder'
+require 'stoplight/configuration'
+require 'stoplight/light/lockable'
 require 'stoplight/light/runnable'
 require 'stoplight/light'
 
-# @see Stoplight::Light#initialize
-def Stoplight(name, &code) # rubocop:disable Style/MethodName
-  Stoplight::Light.new(name, &code)
+# @return [Stoplight::CircuitBreaker]
+def Stoplight(name, &code) # rubocop:disable Naming/MethodName
+  if block_given?
+    warn '[DEPRECATED] Calling `Stoplight("name") { ... }` with a code block is deprecated. ' \
+      'Please pass code block to the run method `Stoplight("name").run { ... }` method instead.'
+    Stoplight::Builder.with(name: name).build(&code)
+  else
+    Stoplight::Builder.with(name: name)
+  end
 end

data/spec/spec_helper.rb

@@ -4,10 +4,17 @@ require 'simplecov'
 
 require 'stoplight'
 require 'timecop'
+require_relative 'support/data_store/base'
+require_relative 'support/light/runnable'
+require_relative 'support/configurable'
+require_relative 'support/database_cleaner'
+require_relative 'support/exception_helpers'
 
 Timecop.safe_mode = true
 
 RSpec.configure do |rspec|
+  rspec.include ExceptionHelpers
+
   rspec.color = true
   rspec.disable_monkey_patching!
   rspec.order = :random

data/spec/stoplight/builder_spec.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'securerandom'
+
+RSpec.describe Stoplight::Builder do
+  let(:name) { SecureRandom.uuid }
+
+  describe '.with' do
+    context 'with only name' do
+      subject(:configuration) { builder.configuration }
+
+      let(:builder) { described_class.with(name: name) }
+
+      it 'sets configuration to default values' do
+        expect(configuration).to have_attributes(
+          name: name,
+          data_store: Stoplight.default_data_store,
+          notifiers: Stoplight.default_notifiers,
+          cool_off_time: Stoplight::Default::COOL_OFF_TIME,
+          threshold: Stoplight::Default::THRESHOLD,
+          window_size: Stoplight::Default::WINDOW_SIZE
+        )
+      end
+    end
+
+    context 'with configured parameters' do
+      subject(:configuration) { builder.configuration }
+
+      let(:builder) { described_class.with(**configured_parameters) }
+      let(:configured_parameters) do
+        {
+          name: name,
+          data_store: 42,
+          notifiers: [43],
+          cool_off_time: 44,
+          threshold: 45,
+          window_size: 46
+        }
+      end
+
+      it 'sets configuration parameters' do
+        expect(configuration).to have_attributes(**configured_parameters)
+      end
+    end
+  end
+
+  describe '.build' do
+    let(:builder) { described_class.new(configuration) }
+    let(:configuration) { instance_double(Stoplight::Configuration, name: name) }
+
+    context 'with code' do
+      subject(:light) { builder.build(&code) }
+
+      let(:code) { -> { 42 } }
+
+      it 'builds new light' do
+        expect(light.configuration).to eq(configuration)
+        expect(light.code).to eq(code)
+      end
+    end
+
+    context 'without code' do
+      subject(:light) { builder.build }
+
+      it 'builds new light' do
+        expect(light.configuration).to eq(configuration)
+        expect(light.code).to eq(nil)
+      end
+    end
+  end
+
+  context 'methods building an instance of light' do
+    let(:builder) { described_class.new(configuration) }
+    let(:configuration) do
+      Stoplight::Configuration.new(
+        name: name,
+        data_store: Stoplight.default_data_store,
+        notifiers: Stoplight.default_notifiers,
+        cool_off_time: Stoplight::Default::COOL_OFF_TIME,
+        threshold: Stoplight::Default::THRESHOLD,
+        window_size: Stoplight::Default::WINDOW_SIZE,
+        error_notifier: Stoplight.default_error_notifier
+      )
+    end
+
+    describe '#with_error_handler' do
+      subject(:light) { builder.with_error_handler(&error_handler) }
+
+      let(:error_handler) { ->(error, handle) {} }
+
+      it 'returns an instance of the Light class with this configuration set' do
+        expect(light.configuration).to be(configuration)
+        expect(light.error_handler).to eq(error_handler)
+      end
+    end
+
+    describe '#with_fallback' do
+      subject(:light) { builder.with_fallback(&fallback) }
+
+      let(:fallback) { ->(error) {} }
+
+      it 'returns an instance of the Light class with this configuration set' do
+        expect(light.configuration).to be(configuration)
+        expect(light.fallback).to eq(fallback)
+      end
+    end
+
+    describe '#run' do
+      it 'yields the block' do
+        expect do |code|
+          builder.run(&code)
+        end.to yield_control
+      end
+    end
+
+    describe '#lock' do
+      context 'when the light is not locked' do
+        it 'locks the light' do
+          expect { builder.lock(Stoplight::Color::RED) }
+            .to change(builder, :color)
+            .from(Stoplight::Color::GREEN)
+            .to(Stoplight::Color::RED)
+        end
+      end
+
+      context 'when the light is locked' do
+        before do
+          builder.lock(Stoplight::Color::RED)
+        end
+
+        it 'does not change the light' do
+          expect { builder.lock(Stoplight::Color::RED) }
+            .not_to change(builder, :color)
+            .from(Stoplight::Color::RED)
+        end
+      end
+    end
+
+    describe '#unlock' do
+      context 'when the light is not locked' do
+        it 'does nothing' do
+          expect { builder.unlock }
+            .not_to change(builder, :color)
+            .from(Stoplight::Color::GREEN)
+        end
+      end
+
+      context 'when the light is locked' do
+        before do
+          builder.lock(Stoplight::Color::RED)
+        end
+
+        it 'unlocks the light' do
+          expect { builder.unlock }
+            .to change(builder, :color)
+            .from(Stoplight::Color::RED)
+            .to(Stoplight::Color::GREEN)
+        end
+      end
+    end
+  end
+
+  it_behaves_like Stoplight::Configurable
+end

data/spec/stoplight/circuit_breaker_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Stoplight::CircuitBreaker do
+  subject(:circuit_breaker) { klass.new }
+
+  let(:klass) do
+    Class.new { include Stoplight::CircuitBreaker }
+  end
+
+  specify '#with_error_handler' do
+    expect { circuit_breaker.with_error_handler {} }.to raise_error(NotImplementedError)
+  end
+
+  specify '#with_fallback' do
+    expect { circuit_breaker.with_fallback {} }.to raise_error(NotImplementedError)
+  end
+
+  specify '#color' do
+    expect { circuit_breaker.color }.to raise_error(NotImplementedError)
+  end
+
+  specify '#run' do
+    expect { circuit_breaker.run {} }.to raise_error(NotImplementedError)
+  end
+
+  specify '#lock' do
+    expect { circuit_breaker.lock('red') }.to raise_error(NotImplementedError)
+  end
+
+  specify '#unlock' do
+    expect { circuit_breaker.unlock }.to raise_error(NotImplementedError)
+  end
+end

data/spec/stoplight/configurable_spec.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Stoplight::Configurable do
+  describe '#with' do
+    subject(:configurable) { configurable_class.new }
+
+    let(:configurable_class) do
+      Class.new do
+        include Stoplight::Configurable
+
+        def configuration
+          Stoplight::Configuration.new(name: 'foo')
+        end
+      end
+    end
+
+    it 'raises NotImplementedError' do
+      expect do
+        configurable.with_data_store(nil)
+      end.to raise_error(NotImplementedError)
+    end
+  end
+end

data/spec/stoplight/data_store/base_spec.rb

@@ -61,4 +61,11 @@ RSpec.describe Stoplight::DataStore::Base do
         .to raise_error(NotImplementedError)
     end
   end
+
+  describe '#with_notification_lock' do
+    it 'is not implemented' do
+      expect { data_store.with_notification_lock(nil, nil, nil) }
+        .to raise_error(NotImplementedError)
+    end
+  end
 end