stoplight 5.4.0 → 5.5.0

data/lib/stoplight/notifier/generic.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Notifier
-    # The Generic module provides a reusable implementation for notifiers in Stoplight.
-    # It includes a formatter for generating notification messages and defines the `notify` method.
-    #
-    # @example Custom Notifier Implementation and Usage
-    #     # Custom notifier that writes notifications to a file
-    #     class FileNotifier < Stoplight::Notifier::Base
-    #       include Stoplight::Notifier::Generic
-    #
-    #       def initialize(file_path)
-    #         @file = File.open(file_path, 'a')
-    #         super(@file)
-    #       end
-    #
-    #       private
-    #
-    #       # Writes the notification message to the file
-    #       def put(message)
-    #         @file.puts(message)
-    #       end
-    #     end
-    #
-    #     # Usage example
-    #     # Create a custom notifier that writes to 'stoplight.log'
-    #     notifier = FileNotifier.new('stoplight.log')
-    #
-    #     # Configure Stoplight to use the custom notifier
-    #     Stoplight.configure do |config|
-    #       config.notifiers += [notifier]
-    #     end
-    #
-    #     # Create a stoplight and trigger a state change
-    #     light = Stoplight('example-light')
-    #     light.run { raise 'Simulated failure' } rescue nil
-    #     light.run { raise 'Simulated failure' } rescue nil
-    #     light.run { raise 'Simulated failure' } rescue nil
-    #
-    module Generic # rubocop:disable Style/Documentation
-      # @!attribute [r] formatter
-      #   @return [Proc] The formatter used to generate notification messages.
-      #   @see Stoplight::Default::FORMATTER
-      attr_reader :formatter
-
-      # @param object [Object] The object used by the notifier (e.g., a logger or external service).
-      # @param formatter [Proc, nil] A custom formatter for generating notification messages.
-      #   If no formatter is provided, the default formatter is used.
-      def initialize(object, formatter = nil)
-        @object = object
-        @formatter = formatter || Default::FORMATTER
-      end
-
-      # Sends a notification when a Stoplight changes state.
-      #
-      # @param light [Light] The Stoplight instance triggering the notification.
-      # @param from_color [String] The previous state color of the Stoplight.
-      # @param to_color [String] The new state color of the Stoplight.
-      # @param error [Exception, nil] The error (if any) that caused the state change.
-      # @return [String] The formatted notification message.
-      def notify(light, from_color, to_color, error)
-        message = formatter.call(light, from_color, to_color, error)
-        put(message)
-        message
-      end
-
-      private
-
-      # Processes the notification message.
-      #
-      # @param message [String] The notification message to be processed.
-      # @raise [NotImplementedError] If the method is not implemented in a subclass.
-      def put(message)
-        raise NotImplementedError
-      end
-    end
-  end
-end

data/lib/stoplight/notifier/io.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Notifier
-    # @see Base
-    class IO < Base
-      include Generic
-
-      # @return [::IO]
-      def io
-        @object
-      end
-
-      private
-
-      def put(message)
-        io.puts(message)
-      end
-    end
-  end
-end

data/lib/stoplight/notifier/logger.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Notifier
-    # @see Base
-    class Logger < Base
-      include Generic
-
-      # @return [::Logger]
-      def logger
-        @object
-      end
-
-      def put(message)
-        logger.warn(message)
-      end
-    end
-  end
-end

data/lib/stoplight/state.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module State
-    UNLOCKED = "unlocked"
-    LOCKED_GREEN = "locked_green"
-    LOCKED_RED = "locked_red"
-  end
-end

data/lib/stoplight/traffic_control/base.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module TrafficControl
-    # Strategies for determining when a Stoplight should change color to red.
-    #
-    # These strategies evaluate the current state and metrics of a Stoplight to decide
-    # if traffic should be stopped (i.e., if the light should turn RED).
-    #
-    # @example Creating a custom strategy
-    #   class ErrorRateStrategy < Stoplight::TrafficControl::Base
-    #     def check_compatibility(config)
-    #       if config.window_size.nil?
-    #         incompatible("`window_size` should be set")
-    #       else
-    #         compatible
-    #       end
-    #     end
-    #
-    #     def stop_traffic?(config, metadata)
-    #       total = metadata.successes + metadata.failures
-    #       return false if total < 10 # Minimum sample size
-    #
-    #       error_rate = metadata.failures.fdiv(total)
-    #       error_rate >= 0.5 # Stop traffic when error rate reaches 50%
-    #     end
-    #   end
-    #
-    # @abstract
-    # @api private
-    class Base
-      # Checks if the strategy is compatible with the given Stoplight configuration.
-      #
-      # @param config [Stoplight::Light::Config]
-      # @return [Stoplight::Config::CompatibilityResult]
-      # :nocov:
-      def check_compatibility(config)
-        raise NotImplementedError
-      end
-      # :nocov:
-
-      # Determines whether traffic should be stopped based on the Stoplight's
-      # current state and metrics.
-      #
-      # @param config [Stoplight::Light::Config]
-      # @param metadata [Stoplight::Metadata]
-      # @return [Boolean] true if traffic should be stopped (rec), false otherwise (green)
-      def stop_traffic?(config, metadata)
-        raise NotImplementedError
-      end
-
-      # @param other [any]
-      # @return [Boolean]
-      def ==(other)
-        other.is_a?(self.class)
-      end
-
-      # Returns a compatibility result indicating the strategy is compatible.
-      #
-      # @return [Stoplight::Config::CompatibilityResult] A compatible result.
-      private def compatible = Config::CompatibilityResult.compatible
-
-      # Returns a compatibility result indicating the strategy is incompatible.
-      #
-      # @param errors [Array<String>] The list of error messages describing incompatibility.
-      # @return [Stoplight::Config::CompatibilityResult] An incompatible result.
-      private def incompatible(*errors) = Config::CompatibilityResult.incompatible(*errors)
-    end
-  end
-end

data/lib/stoplight/traffic_control/consecutive_errors.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module TrafficControl
-    # A strategy that stops the traffic based on consecutive failures number.
-    #
-    # This strategy implements two distinct behaviors based on whether a window size
-    # is configured:
-    #
-    # 1. When window_size is set: The Stoplight turns red when the total number of
-    #    failures within the window reaches the threshold.
-    #
-    # 2. When window_size is not set: The Stoplight turns red when consecutive failures
-    #    reach the threshold.
-    #
-    # @example With window-based configuration
-    #   traffic_control = Stoplight::TrafficControl::ConsecutiveErrors.new
-    #   config = Stoplight::Light::Config.new(threshold: 5, window_size: 60, traffic_control:)
-    #
-    # Will switch to red if 5 consecutive failures occur within the 60-second window
-    #
-    # @example With total number of consecutive failures configuration
-    #   traffic_control = Stoplight::TrafficControl::ConsecutiveErrors.new
-    #   config = Stoplight::Light::Config.new(threshold: 5, window_size: nil, traffic_control:)
-    #
-    # Will switch to red only if 5 consecutive failures occur regardless of the time window
-    # @api private
-    class ConsecutiveErrors < Base
-      # @param config [Stoplight::Light::Config]
-      # @return [Stoplight::Config::CompatibilityResult]
-      def check_compatibility(config)
-        if config.threshold <= 0
-          incompatible("`threshold` should be bigger than 0")
-        elsif !config.threshold.is_a?(Integer)
-          incompatible("`threshold` should be an integer")
-        else
-          compatible
-        end
-      end
-
-      # Determines if traffic should be stopped based on failure counts.
-      #
-      # @param config [Stoplight::Light::Config]
-      # @param metadata [Stoplight::Metadata]
-      # @return [Boolean] true if failures have reached the threshold, false otherwise
-      def stop_traffic?(config, metadata)
-        if config.window_size
-          [metadata.consecutive_errors, metadata.errors].min >= config.threshold
-        else
-          metadata.consecutive_errors >= config.threshold
-        end
-      end
-    end
-  end
-end

data/lib/stoplight/traffic_control/error_rate.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module TrafficControl
-    # A strategy that stops the traffic based on error rate.
-    #
-    # @example
-    #   traffic_control = Stoplight::TrafficControl::ErrorRate.new
-    #   config = Stoplight::Light::Config.new(threshold: 0.6, window_size: 300, traffic_control:)
-    #
-    # Will switch to red if 60% error rate reached within the 5-minute (300 seconds) sliding window.
-    # By default this traffic control strategy starts evaluating only after 10 requests have been made. You can
-    # adjust this by passing a different value for `min_requests` when initializing the strategy.
-    #
-    #   traffic_control = Stoplight::TrafficControl::ErrorRate.new(min_requests: 100)
-    #
-    # @api private
-    class ErrorRate < Base
-      # @!attribute min_requests
-      #   @return [Integer]
-      attr_reader :min_requests
-
-      # @param min_requests [Integer] Minimum number of requests before traffic control is applied.
-      #   until this number of requests is reached, the error rate will not be considered.
-      def initialize(min_requests: 10)
-        @min_requests = min_requests
-      end
-
-      # @param config [Stoplight::Light::Config]
-      # @return [Stoplight::Config::CompatibilityResult]
-      def check_compatibility(config)
-        if config.window_size.nil?
-          incompatible("`window_size` should be set")
-        elsif config.threshold < 0 || config.threshold > 1
-          incompatible("`threshold` should be between 0 and 1")
-        else
-          compatible
-        end
-      end
-
-      # @param config [Stoplight::Light::Config]
-      # @param metadata [Stoplight::Metadata]
-      # @return [Boolean]
-      def stop_traffic?(config, metadata)
-        metadata.requests >= min_requests && metadata.error_rate >= config.threshold
-      end
-    end
-  end
-end

data/lib/stoplight/traffic_recovery/base.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module TrafficRecovery
-    # Strategies for determining how to recover traffic flow through the Stoplight.
-    # These strategies evaluate recovery metrics to decide which color the Stoplight should
-    # transition to during the recovery process.
-    #
-    # @example Creating a custom traffic recovery strategy
-    #   class GradualRecovery < Stoplight::TrafficRecovery::Base
-    #     def initialize(min_success_rate: 0.8, min_samples: 100)
-    #       @min_success_rate = min_success_rate
-    #       @min_samples = min_samples
-    #     end
-    #
-    #     def determine_color(config, metadata)
-    #       total_probes = metadata.recovery_probe_successes + metadata.recovery_probe_errors
-    #
-    #       if total_probes < @min_samples
-    #         return Color::YELLOW # Keep recovering, not enough samples
-    #       end
-    #
-    #       success_rate = metadata.recovery_probe_successes.fdiv(total_probes)
-    #       if success_rate >= @min_success_rate
-    #         Color::GREEN # Recovery successful
-    #       elsif success_rate <= 0.2
-    #         Color::RED # Recovery failed, too many errors
-    #       else
-    #         Color::YELLOW # Continue recovery
-    #       end
-    #     end
-    #   end
-    #
-    # @abstract
-    # @api private
-    class Base
-      # Checks if the strategy is compatible with the given Stoplight configuration.
-      #
-      # @param config [Stoplight::Light::Config]
-      # @return [Stoplight::Config::CompatibilityResult]
-      # :nocov:
-      def check_compatibility(config)
-        raise NotImplementedError
-      end
-      # :nocov:
-
-      # Determines the appropriate recovery state based on the Stoplight's
-      # current metrics and recovery progress.
-      #
-      # @param config [Stoplight::Light::Config]
-      # @param metadata [Stoplight::Metadata]
-      # @return [TrafficRecovery::Decision]
-      def determine_color(config, metadata)
-        raise NotImplementedError
-      end
-
-      # @param other [any]
-      # @return [Boolean]
-      def ==(other)
-        other.is_a?(self.class)
-      end
-
-      # Returns a compatibility result indicating the strategy is compatible.
-      #
-      # @return [Stoplight::Config::CompatibilityResult] A compatible result.
-      private def compatible = Config::CompatibilityResult.compatible
-
-      # Returns a compatibility result indicating the strategy is incompatible.
-      #
-      # @param errors [Array<String>] The list of error messages describing incompatibility.
-      # @return [Stoplight::Config::CompatibilityResult] An incompatible result.
-      private def incompatible(*errors) = Config::CompatibilityResult.incompatible(*errors)
-    end
-  end
-end

data/lib/stoplight/traffic_recovery/consecutive_successes.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module TrafficRecovery
-    # A conservative strategy that requires multiple consecutive successful probes
-    # before resuming traffic flow.
-    #
-    # The strategy immediately returns to RED state if any failure occurs during
-    # the recovery process, ensuring that only truly stable services resume
-    # full traffic flow.
-    #
-    # @example Basic usage with 3 consecutive successes required
-    #   config = Stoplight::Light::Config.new(
-    #     cool_off_time: 60,
-    #     recovery_threshold: 3
-    #   )
-    #   strategy = Stoplight::TrafficRecovery::ConsecutiveSuccesses.new
-    #
-    # Recovery behavior:
-    # - After cool-off period, Stoplight enters YELLOW (recovery) state
-    # - Requires 3 consecutive successful probes to transition to GREEN
-    # - Any failure during recovery immediately returns to RED state
-    # - Process repeats after another cool-off period
-    #
-    # Configuration requirements:
-    # - `recovery_threshold`: Integer > 0, specifies required consecutive successes
-    #
-    # Failure behavior:
-    # Unlike some circuit breaker implementations that tolerate occasional failures
-    # during recovery, this strategy takes a zero-tolerance approach: any failure
-    # during the recovery phase immediately transitions back to RED state. This
-    # conservative approach prioritizes stability over recovery speed.
-    #
-    # @api private
-    class ConsecutiveSuccesses < Base
-      # @param config [Stoplight::Light::Config]
-      # @return [Stoplight::Config::CompatibilityResult]
-      def check_compatibility(config)
-        if config.recovery_threshold <= 0
-          incompatible("`recovery_threshold` should be bigger than 0")
-        elsif !config.recovery_threshold.is_a?(Integer)
-          incompatible("`recovery_threshold` should be an integer")
-        else
-          compatible
-        end
-      end
-
-      # Determines if traffic should be resumed based on successes counts.
-      #
-      # @param config [Stoplight::Light::Config]
-      # @param metadata [Stoplight::Metadata]
-      # @return [TrafficRecovery::Decision]
-      def determine_color(config, metadata)
-        return TrafficRecovery::PASS if metadata.color != Color::YELLOW
-
-        recovery_started_at = metadata.recovery_started_at || metadata.recovery_scheduled_after
-
-        if metadata.last_error_at && metadata.last_error_at >= recovery_started_at
-          TrafficRecovery::RED
-        elsif [metadata.consecutive_successes, metadata.recovery_probe_successes].min >= config.recovery_threshold
-          TrafficRecovery::GREEN
-        else
-          TrafficRecovery::YELLOW
-        end
-      end
-    end
-  end
-end

data/lib/stoplight/traffic_recovery.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module TrafficRecovery
-    Decision = Data.define(:decision)
-    GREEN = Decision.new("green")
-    YELLOW = Decision.new("yellow")
-    RED = Decision.new("red")
-    PASS = Decision.new("pass")
-  end
-end