stoplight 5.7.0 → 5.8.2

data/lib/stoplight/domain/error.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Domain
-    module Error
-      Base = Class.new(StandardError)
-      ConfigurationError = Class.new(Base)
-      IncorrectColor = Class.new(Base)
-
-      class RedLight < Base
-        # @!attribute light_name
-        #   @return [String] The light's name
-        attr_reader :light_name
-
-        # @!attribute cool_off_time
-        #   @return [Numeric] Cool-off period in seconds
-        attr_reader :cool_off_time
-
-        # @!attribute retry_after
-        #   @return [Time] Absolute Time after which a recovery attempt can occur
-        attr_reader :retry_after
-
-        # Initializes a new RedLight error.
-        #
-        # @param light_name [String] The light's name
-        #
-        # @option cool_off_time [Numeric] Cool-off period in seconds
-        #
-        # @option retry_after [Time] Absolute Time after which a recovery attempt can occur
-        #
-        # @return [Stoplight::Error::RedLight]
-        def initialize(light_name, cool_off_time:, retry_after:)
-          @light_name = light_name
-          @cool_off_time = cool_off_time
-          @retry_after = retry_after
-
-          super(light_name)
-        end
-      end
-    end
-  end
-end

data/lib/stoplight/domain/metrics.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Domain
-    # Request metrics over a given window.
-    #
-    # @!attribute successes
-    #   A number of successes withing requested window. Zero for non-windowed metrics
-    #   @return [Integer]
-    #
-    # @!attribute errors
-    #   A number of errors withing requested window. Zero for non-windowed metrics
-    #   @return [Integer]
-    #
-    # @!attribute consecutive_errors
-    #   A number of consecutive errors
-    #   @return [Integer]
-    #
-    # @!attribute consecutive_successes
-    #   A number of consecutive successes
-    #   @return [Integer]
-    #
-    # @!attribute last_error
-    #   @return [Stoplight::Domain::Failure, nil]
-    #
-    # @!attribute last_success_at
-    #   @return [Time, nil]
-    #
-    # @api private
-    Metrics = Data.define(
-      :successes,
-      :errors,
-      :consecutive_errors,
-      :consecutive_successes,
-      :last_error,
-      :last_success_at
-    ) do
-      # Calculates the error rate based on the number of successes and errors.
-      #
-      # @return [Float]
-      def error_rate
-        return unless requests # we effectively check if this is windowed metrics
-
-        if (successes + errors).zero?
-          0.0
-        else
-          errors.fdiv(successes + errors)
-        end
-      end
-
-      # @return [Integer]
-      def requests
-        if successes && errors # we effectively check if this is windowed metrics
-          successes + errors
-        end
-      end
-
-      # @return [Time, nil]
-      def last_error_at
-        last_error&.time
-      end
-    end
-  end
-end

data/lib/stoplight/domain/recovery_lock_token.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Domain
-    # Token representing an acquired recovery lock.
-    #
-    # Returned by +DataStore#acquire_recovery_lock+ and passed to
-    # +DataStore#release_recovery_lock+ to identify which lock to release.
-    #
-    # The actual locking mechanism lives in DataStore implementations,
-    # not in these tokens.
-    class RecoveryLockToken
-    end
-  end
-end

data/lib/stoplight/domain/state.rb

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

data/lib/stoplight/domain/state_transition_notifier.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Domain
-    # Base class for creating custom notifiers in Stoplight.
-    # This is an abstract class that defines the interface for notifiers.
-    #
-    # @abstract Subclasses must implement the `notify` method to define custom notification logic.
-    # :nocov:
-    class StateTransitionNotifier # ColorTransition?????
-      # Sends a notification when a Stoplight changes state.
-      #
-      # @param config [Stoplight::Domain::Config] 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 result of the notification process.
-      #
-      def notify(config, from_color, to_color, error)
-        raise NotImplementedError
-      end
-    end
-    # :nocov:
-  end
-end

data/lib/stoplight/domain/storage/metrics.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Domain
-    module Storage
-      # Encapsulates metrics storage for circuit breaker execution tracking.
-      #
-      # This abstraction isolates metrics collection and retrieval from the
-      # broader data store concerns, enabling:
-      # - Purpose-built implementations optimized for time-series data
-      # - Independent scaling and optimization of metrics vs. state storage
-      # - Clearer separation between "what happened" (metrics) and "what to do" (state)
-      #
-      # Lifecycle: A Metrics instance is scoped to a single circuit breaker
-      # configuration. Each circuit gets its own metrics store instance,
-      # allowing different circuits to use different storage strategies.
-      #
-      # @abstract
-      class Metrics
-        # Retrieves a snapshot of current metrics for decision-making.
-        #
-        # @return [Stoplight::Domain::Metrics]
-        def metrics_snapshot = raise NotImplementedError
-
-        # Records a successful circuit breaker execution
-        #
-        # @return [void]
-        def record_success = raise NotImplementedError
-
-        # Records a failed circuit breaker execution
-        #
-        # @param error [StandardError]
-        # @return [void]
-        def record_failure(error) = raise NotImplementedError
-
-        # Clears all metrics for this circuit
-        # @return [void]
-        def clear = raise NotImplementedError
-      end
-    end
-  end
-end

data/lib/stoplight/domain/storage/recovery_lock.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Domain
-    module Storage
-      # Encapsulates recovery lock management for coordinating recovery probes.
-      #
-      # When a circuit enters YELLOW state (half-open), it begins sending
-      # "recovery probes" - test requests to check if the protected service
-      # has recovered. In distributed deployments with multiple instances,
-      # recovery locks ensure only ONE instance sends probes at a time.
-      #
-      # Without coordination, all instances would simultaneously:
-      # 1. Detect the circuit is YELLOW
-      # 2. Send recovery probes to the struggling service
-      # 3. Potentially overwhelm it with "test" traffic
-      #
-      # Lock Lifecycle:
-      #
-      #   Instance A: acquire_lock -> probe -> release_lock
-      #   Instance B: acquire_lock -> nil (already held) -> skip probe
-      #   Instance C: acquire_lock -> nil (already held) -> skip probe
-      #
-      # Lock Semantics:
-      # - Returns +nil+ if lock is already held. Never blocks waiting for lock availability
-      # - Locks must automatically expire when persisted storage is used
-      # - Failed releases are acceptable (timeout provides safety)
-      #
-      # @abstract
-      # @see Stoplight::Domain::Strategies::YellowRunStrategy
-      class RecoveryLock
-        # Attempts to acquire recovery lock for exclusive probe execution.
-        #
-        # This method tries to acquire a lock that serializes recovery probe
-        # execution across multiple instances. If the lock is already held by
-        # another instance, returns +nil+ immediately without blocking.
-        #
-        # @return [Stoplight::Domain::RecoveryLockToken, nil]
-        #   - +RecoveryLockToken+: Lock acquired, caller should send probe
-        #   - +nil+: Lock unavailable, another instance is probing
-        #
-        def acquire_lock = raise NotImplementedError
-
-        # Releases a previously acquired lock.
-        #
-        # This method releases the lock token returned by +#acquire_lock+,
-        # allowing other instances to acquire it. Release should be called
-        # in an ensure block to guarantee cleanup even if probe fails.
-        #
-        # @param lock [Stoplight::Domain::RecoveryLockToken] The token returned by +#acquire_lock+
-        # @return [void]
-        def release_lock(lock) = raise NotImplementedError
-      end
-    end
-  end
-end

data/lib/stoplight/domain/storage/state.rb

@@ -1,87 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Domain
-    module Storage
-      # Encapsulates circuit breaker state storage.
-      #
-      # State management handles the current operational mode of a circuit breaker:
-      # - Color (GREEN/YELLOW/RED) - whether the circuit is open or closed
-      # - Lock state (LOCKED_GREEN/LOCKED_RED/UNLOCKED) - manual overrides
-      # - State transitions - tracking color changes for notifications #
-      #
-      # State requires stronger consistency than metrics because:
-      # - Multiple instances must agree on circuit color
-      # - Race conditions during transitions must be handled
-      # - Lock states must be immediately visible across instances
-      #
-      # @abstract
-      # @see Stoplight::Domain::Storage::Metrics
-      class State
-        # Retrieves current state snapshot for decision-making.
-        #
-        # The snapshot is an immutable view of the circuit's current state,
-        # including its color and lock status. This method is called on every
-        # circuit breaker invocation to determine whether to allow traffic.
-        #
-        # This is called on every request, so implementations should be fast.
-        #
-        # @return [Stoplight::Domain::StateSnapshot]
-        def state_snapshot = raise NotImplementedError
-
-        # Sets the lock state of the circuit.
-        #
-        # Locks allow manual override of circuit behavior:
-        # - LOCKED_GREEN: Force circuit closed (allow all traffic)
-        # - LOCKED_RED: Force circuit open (block all traffic)
-        # - UNLOCKED: Follow normal circuit breaker rules
-        #
-        # Lock states take precedence over color states. A locked circuit
-        # ignores failure thresholds and stays in the locked state until
-        # explicitly unlocked.
-        #
-        # Use Cases:
-        # - Emergency traffic control during incidents
-        # - Maintenance windows (lock RED to prevent traffic)
-        # - Gradual rollout (lock GREEN during testing)
-        #
-        # @param state [String] The new state to set.
-        # @return [String] The state that was set.
-        def set_state(state) = raise NotImplementedError
-
-        # Transitions the Stoplight to the specified color.
-        #
-        # This method performs a color transition operation that works across distributed instances
-        # of the light. It ensures that in a multi-instance environment, only one instance
-        # is considered the "first" to perform the transition (and therefore responsible for
-        # triggering notifications).
-        #
-        # @param color [String] The target color/state to transition to.
-        #   Should be one of Stoplight::Color::GREEN, Stoplight::Color::YELLOW, or Stoplight::Color::RED.
-        #
-        # @return [Boolean] Returns +true+ if this instance was the first to perform this specific transition
-        #   (and should therefore trigger notifications). Returns +false+ if another instance already
-        #   initiated this transition.
-        #
-        # @note In distributed environments with multiple instances, race conditions can occur when instances
-        #   attempt conflicting transitions simultaneously (e.g., one instance tries to transition from
-        #   YELLOW to GREEN while another tries YELLOW to RED). The implementation handles this, but
-        #   be aware that the last operation may determine the final color of the light.
-        #
-        def transition_to_color(color) = raise NotImplementedError
-
-        # Clears all state data for this circuit.
-        #
-        # This removes the circuit from storage entirely, resetting it to
-        # default (unlocked, green) state. The next invocation will start
-        # with fresh state.
-        #
-        # @note This does NOT clear metrics. If you want to fully
-        # reset a circuit, clear both state and metrics stores.
-        #
-        # @return [void]
-        def clear = raise NotImplementedError
-      end
-    end
-  end
-end

data/lib/stoplight/domain/strategies/run_strategy.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Domain
-    module Strategies
-      # Represents an abstract strategy for running a light's operations.
-      # Every new strategy should be a child of this class.
-      #
-      # @api private
-      # @abstract
-      class RunStrategy
-        # @param fallback [Proc, nil] A fallback proc to execute in case of an error.
-        # @param state_snapshot [Stoplight::Domain::StateSnapshot]
-        # :nocov:
-        def execute(fallback, state_snapshot:, &code)
-          raise NotImplementedError, "Subclasses must implement the execute method"
-        end
-        # :nocov:
-      end
-    end
-  end
-end

data/lib/stoplight/domain/traffic_control/base.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Domain
-    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::Domain::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, metrics)
-      #       total = metrics.successes + metrics.failures
-      #       return false if total < 10 # Minimum sample size
-      #
-      #       error_rate = metrics.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::Domain::Config]
-        # @return [Stoplight::Domain::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::Domain::Config]
-        # @param metrics [Stoplight::Domain::Metrics]
-        # @return [Boolean] true if traffic should be stopped (rec), false otherwise (green)
-        # :nocov:
-        def stop_traffic?(config, metrics)
-          raise NotImplementedError
-        end
-        # :nocov:
-
-        # @param other [any]
-        # @return [Boolean]
-        def ==(other)
-          other.is_a?(self.class)
-        end
-
-        # Returns a compatibility result indicating the strategy is compatible.
-        #
-        # @return [Stoplight::Domain::CompatibilityResult] A compatible result.
-        private def compatible = CompatibilityResult.compatible
-
-        # Returns a compatibility result indicating the strategy is incompatible.
-        #
-        # @param errors [Array<String>] The list of error messages describing incompatibility.
-        # @return [Stoplight::Domain::CompatibilityResult] An incompatible result.
-        private def incompatible(*errors) = CompatibilityResult.incompatible(*errors)
-      end
-    end
-  end
-end

data/lib/stoplight/domain/traffic_recovery/base.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Domain
-    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::Domain::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, metrics)
-      #       total_probes = metrics.recovery_probe_successes + metrics.recovery_probe_errors
-      #
-      #       if total_probes < @min_samples
-      #         return Color::YELLOW # Keep recovering, not enough samples
-      #       end
-      #
-      #       success_rate = metrics.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::Domain::Config]
-        # @return [Stoplight::Domain::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::Domain::Config]
-        # @param metrics [Stoplight::Domain::Metrics]
-        # @return [TrafficRecovery::Decision]
-        # :nocov:
-        def determine_color(config, metrics)
-          raise NotImplementedError
-        end
-        # :nocov:
-
-        # @param other [any]
-        # @return [Boolean]
-        def ==(other)
-          other.is_a?(self.class)
-        end
-
-        # Returns a compatibility result indicating the strategy is compatible.
-        #
-        # @return [Stoplight::Domain::CompatibilityResult] A compatible result.
-        private def compatible = CompatibilityResult.compatible
-
-        # Returns a compatibility result indicating the strategy is incompatible.
-        #
-        # @param errors [Array<String>] The list of error messages describing incompatibility.
-        # @return [Stoplight::Domain::CompatibilityResult] An incompatible result.
-        private def incompatible(*errors) = CompatibilityResult.incompatible(*errors)
-      end
-    end
-  end
-end

data/lib/stoplight/wiring/data_store/base.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Wiring
-    module DataStore
-      # @abstract
-      class Base
-      end
-    end
-  end
-end

data/lib/stoplight/wiring/data_store/redis.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Wiring
-    module DataStore
-      class Redis < Base
-        # @!attribute redis
-        #   @return [::Redis, ConnectionPool<::Redis>]
-        attr_reader :redis
-
-        # @!attribute warn_on_clock_skew
-        #   @return [Boolean]
-        attr_reader :warn_on_clock_skew
-
-        # @param redis [::Redis, ConnectionPool<::Redis>]
-        # @param warn_on_clock_skew [Boolean] (true) Whether to warn about clock skew between Redis and
-        #   the application server
-        def initialize(redis, warn_on_clock_skew: true)
-          @warn_on_clock_skew = warn_on_clock_skew
-          @redis = redis
-        end
-      end
-    end
-  end
-end

data/lib/stoplight/wiring/default_factory_builder.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Wiring
-    # Builds the default LightFactory from user-provided configuration which is
-    # used as the basis for all circuit breakers.
-    #
-    class DefaultFactoryBuilder
-      # @!attribute [r] configuration
-      #  @return [Stoplight::Wiring::DefaultConfiguration]
-      #
-      attr_reader :configuration
-
-      def initialize
-        @configuration = DefaultConfiguration.new
-      end
-
-      # @return [Stoplight::Wiring::LightFactory]
-      # @api private the method is used internally by Stoplight
-      def build
-        LightFactory.new(configuration.to_h)
-      end
-    end
-  end
-end

data/lib/stoplight/wiring/light/default_config.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Wiring
-    module Light
-      # Provides default settings for the Stoplight library.
-      # @api private
-      DefaultConfig = Domain::Config.empty.with(
-        cool_off_time: Default::COOL_OFF_TIME,
-        threshold: Default::THRESHOLD,
-        recovery_threshold: Default::RECOVERY_THRESHOLD,
-        window_size: Default::WINDOW_SIZE,
-        tracked_errors: Default::TRACKED_ERRORS,
-        skipped_errors: Default::SKIPPED_ERRORS
-      )
-    end
-  end
-end

data/lib/stoplight/wiring/light/system_config.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Wiring
-    module Light
-      SystemConfig = DefaultConfig.with(
-        recovery_threshold: 3
-      )
-    end
-  end
-end

data/lib/stoplight/wiring/light_factory/compatibility_validator.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Stoplight
-  module Wiring
-    class LightFactory
-      # Validates that traffic control and recovery strategies are
-      # compatible with the provided configuration.
-      #
-      # Different strategies have different configuration requirements:
-      # - ErrorRate requires window_size and threshold ∈ [0,1]
-      # - ConsecutiveErrors requires threshold > 0
-      # - ConsecutiveSuccesses requires recovery_threshold > 0
-      #
-      # @raise [Stoplight::Error::ConfigurationError] if incompatible
-      class CompatibilityValidator
-        private attr_reader :dependencies
-        private attr_reader :config
-
-        class << self
-          def call(config, dependencies) = new(config, dependencies).call
-        end
-
-        def initialize(config, dependencies)
-          @config = config
-          @dependencies = dependencies
-        end
-
-        def call
-          validate_traffic_control!
-          validate_traffic_recovery!
-        end
-
-        private def validate_traffic_control!
-          traffic_control = dependencies.fetch(:traffic_control)
-          traffic_control.check_compatibility(config).then do |compatibility_result|
-            if compatibility_result.incompatible?
-              raise Domain::Error::ConfigurationError,
-                "#{traffic_control.class.name} incompatible with config: #{compatibility_result.error_messages}"
-            end
-          end
-        end
-
-        def validate_traffic_recovery!
-          traffic_recovery = dependencies.fetch(:traffic_recovery)
-          traffic_recovery.check_compatibility(config).then do |compatibility_result|
-            if compatibility_result.incompatible?
-              raise Domain::Error::ConfigurationError,
-                "#{traffic_recovery.class.name} incompatible with config: #{compatibility_result.error_messages}"
-            end
-          end
-        end
-      end
-    end
-  end
-end