stoplight 5.4.0 → 5.5.0

data/lib/stoplight/infrastructure/dependency_injection/container.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module DependencyInjection
+      # Generic dependency injection container for managing object dependencies.
+      #
+      # This is a low-level infrastructure component that provides the mechanism for
+      # dependency resolution. It has no knowledge of Stoplight's domain concepts and
+      # could theoretically be used in any Ruby application.
+      #
+      # The container supports three resolution strategies:
+      #
+      # 1. **Direct dependencies** - Pre-configured values stored in the container
+      # 2. **Lazy initialization** - Dependencies that are transformed on first access
+      # 3. **Factories** - Dependencies computed dynamically from other dependencies
+      #
+      # @example Basic usage with direct dependencies
+      #   container = Container.new
+      #   container.register(:logger, Logger.new)
+      #   container.resolve(:logger) #=> #<Logger...>
+      #
+      # @example Using lazy initialization
+      #   container.register(:redis, "redis://localhost:6379") do |url|
+      #     Redis.new(url)
+      #   end
+      #   container.resolve(:redis) #=> #<Redis @connection_string="redis://localhost:6379">
+      #
+      # @example Using factories for computed dependencies
+      #   container.register(:config, my_config)
+      #   container.factory(:service) do
+      #     MyService.new(config: resolve(:config))
+      #   end
+      #   container.resolve(:service) #=> #<MyService...>
+      #
+      # @example Building a container with DSL
+      #   container = Container.define do
+      #     register(:port, 3000)
+      #     register(:host, "localhost")
+      #
+      #     factory(:server) do
+      #       Server.new(host: resolve(:host), port: resolve(:port))
+      #     end
+      #   end
+      #
+      # @api private
+      class Container
+        # @!attribute [r] dependencies
+        #   Stores registered dependency values
+        #   @return [Hash{Symbol => Object}]
+        protected attr_reader :dependencies
+
+        # @!attribute [r] factories
+        #   Stores factory blocks for computed dependencies
+        #   @return [Hash{Symbol => Proc}]
+        protected attr_reader :factories
+
+        # @!attribute [r] initializers
+        #   Stores optional transformation blocks for dependencies
+        #   @return [Hash{Symbol => Proc}]
+        protected attr_reader :initializers
+
+        class << self
+          # Define a container using a DSL block.
+          #
+          # This is a convenience method for creating and configuring a container
+          # in a single expression.
+          #
+          # @yield Block evaluated in the context of the new container
+          # @return [Stoplight::Infrastructure::DependencyInjection::Container] Configured container instance
+          #
+          # @example
+          #   container = Container.define do
+          #     register(:redis_url, "redis://localhost:6379")
+          #     factory(:redis) { Redis.new(resolve(:redis_url)) }
+          #   end
+          def define(&definition)
+            new.define(&definition)
+          end
+        end
+
+        # Creates a new dependency injection container.
+        #
+        # @param dependencies [Hash{Symbol => Object}]
+        # @param factories [Hash{Symbol => Proc}]
+        # @param initializers [Hash{Symbol => Proc}]
+        def initialize(dependencies: {}, factories: {}, initializers: {})
+          @dependencies = dependencies
+          @initializers = initializers
+          @factories = factories
+        end
+
+        # Evaluate a configuration block in the context of this container.
+        #
+        # @yield Block evaluated in the context of the container
+        # @return [Stoplight::Infrastructure::DependencyInjection::Container] self for method chaining
+        #
+        # @example
+        #   container = Container.new
+        #   container.define do
+        #     register(:port, 8080)
+        #     factory(:server) { Server.new(port: resolve(:port)) }
+        #   end
+
+        def define(&definition)
+          instance_eval(&definition)
+          freeze
+          self
+        end
+
+        # Registers a dependency value with optional lazy initialization.
+        #
+        # The initializer block is called every time the dependency is resolved,
+        # receiving the registered value as an argument. This allows for delayed
+        # object construction or transformation of simple values into complex objects.
+        #
+        # @param name [Symbol] The dependency key
+        # @param value [Object] The dependency value (may be transformed by initializer)
+        # @yield [value] Optional transformation block
+        # @yieldparam value [Object] The registered value
+        # @yieldreturn [Object] The transformed value to return when resolving
+        # @return [Stoplight::Infrastructure::DependencyInjection::Container] self for method chaining
+        #
+        # @example Register a simple dependency
+        #   container.register(:port, 3000)
+        #   container.resolve(:port) #=> 3000
+        #
+        # @example Register with lazy initialization
+        #   container.register(:redis, "redis://localhost:6379") do |url|
+        #     Redis.new(url)
+        #   end
+        #   container.resolve(:redis) #=> #<Redis...>
+        #
+        # @example Initialization is applied on every resolution
+        #   container.register(:timestamp, Time.now, &:to_i)
+        #   container.resolve(:timestamp) #=> 1234567890
+        #
+        #   # Update the value
+        #   container.register(:timestamp, Time.now + 60)
+        #   container.resolve(:timestamp) #=> 1234567950 (new timestamp)
+        #
+        def register(name, value, &initializer)
+          dependencies[name] = value
+          initializers[name] = initializer if block_given?
+          self
+        end
+
+        # Resolves a dependency by name.
+        #
+        # Resolution order:
+        # 1. Direct dependency with initializer (value is transformed)
+        # 2. Direct dependency without initializer (value returned as-is)
+        # 3. Factory (block evaluated in container context)
+        # 4. Raises {Stoplight::Infrastructure::DependencyInjection::UnresolvedDependencyError}
+        #
+        # @param name [Symbol] The dependency key
+        # @return [Object] The resolved dependency value
+        # @raise [Stoplight::Infrastructure::DependencyInjection::UnresolvedDependencyError] if dependency is not registered
+        #
+        def resolve(name)
+          if dependencies.key?(name)
+            value = dependencies[name]
+            if initializers.key?(name)
+              initializer = initializers[name]
+              instance_exec(value, &initializer)
+            else
+              value
+            end
+          elsif factories.key?(name)
+            factory = factories[name]
+            instance_eval(&factory)
+          else
+            raise UnresolvedDependencyError, name
+          end
+        end
+
+        # Registers a factory for computing dependencies dynamically.
+        #
+        # Factories are evaluated lazily when the dependency is resolved.
+        # The factory block is evaluated in the container's context, giving
+        # it access to the +#resolve+ method for accessing other dependencies.
+        #
+        # Unlike +#register+ with an initializer, factories are not cached -
+        # they are executed every time the dependency is resolved.
+        #
+        # @param key [Symbol] The dependency key
+        # @yield Factory block evaluated in container context
+        # @yieldreturn [Object] The computed dependency value
+        # @return [Stoplight::Infrastructure::DependencyInjection::Container] self for method chaining
+        #
+        def factory(key, &factory)
+          factories[key] = factory
+          self
+        end
+
+        # Returns all registered dependency keys.
+        #
+        # This includes both direct dependencies and factory definitions.
+        #
+        # @return [Array<Symbol>] All registered dependency keys
+        #
+        # @example
+        #   container.register(:port, 3000)
+        #   container.factory(:server) { Server.new }
+        #   container.keys #=> [:port, :server]
+        #
+        def keys
+          factories.keys | dependencies.keys
+        end
+
+        # Creates a new container with merged dependencies.
+        #
+        # This is an immutable operation - the original container is not modified.
+        # Factories and initializers are copied to the new container.
+        #
+        # @param new_dependencies [Hash{Symbol => Object}] Dependencies to merge/override
+        # @return [Stoplight::Infrastructure::DependencyInjection::Container] New container with merged dependencies
+        #
+        # @example Creating specialized containers
+        #   base = Container.define do
+        #     register(:host, "localhost")
+        #     register(:port, 3000)
+        #   end
+        #
+        #   production = base.with(host: "prod.example.com", port: 80)
+        #   staging = base.with(host: "staging.example.com", port: 8080)
+        #
+        #   base.resolve(:port) #=> 3000
+        #   production.resolve(:port) #=> 80
+        #   staging.resolve(:port) #=> 8080
+
+        def with(**new_dependencies)
+          self.class.new(
+            dependencies: {**dependencies, **new_dependencies},
+            factories:,
+            initializers:
+          )
+        end
+
+        def ==(other)
+          other.is_a?(self.class) &&
+            other.dependencies == dependencies &&
+            other.factories == factories &&
+            other.initializers == initializers
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/dependency_injection/unresolved_dependency_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    module DependencyInjection
+      class UnresolvedDependencyError < Domain::Error::Base
+        def initialize(key)
+          super("Unable to resolve dependency: `#{key}`")
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/notifier/generic.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Infrastructure
+    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::Domain::StateTransitionNotifier
+      #       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
+
+        DEFAULT_FORMATTER = lambda do |light, from_color, to_color, error|
+          words = ["Switching", light.name, "from", from_color, "to", to_color]
+          words += ["because", error.class, error.message] if error
+          words.join(" ")
+        end
+        public_constant :DEFAULT_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.
+        # :nocov:
+        def put(message)
+          raise NotImplementedError
+        end
+        # :nocov:
+      end
+    end
+  end
+end

data/lib/stoplight/infrastructure/notifier/io.rb

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

data/lib/stoplight/infrastructure/notifier/logger.rb

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

data/lib/stoplight/rspec/generic_notifier.rb

@@ -9,7 +9,7 @@ RSpec.shared_examples "a generic notifier" do
     it "is initially the default" do
       formatter = nil
       expect(described_class.new(nil, formatter).formatter)
-        .to eql(Stoplight::Default::FORMATTER)
+        .to eql(Stoplight::Wiring::Default::FORMATTER)
     end
 
     it "reads the formatter" do

data/lib/stoplight/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stoplight
-  VERSION = Gem::Version.new("5.4.0")
+  VERSION = Gem::Version.new("5.5.0")
 end

data/lib/stoplight/wiring/container.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    # This container implements an instance of +Stoplight::Infrastructure::DependencyInjection::Container+
+    # with Stoplight-specific wiring knowledge. It defines how to construct and connect
+    # all the components needed for a circuit breaker to function.
+    #
+    # ## Default Configuration
+    #
+    # The container is pre-configured with sensible defaults:
+    # - Data Store - in-memory storage
+    # - STDERR notifier
+    # - No-op error notifier
+    # - Consecutive failure detection
+    # - Consecutive success recovery
+    #
+    # @see Infrastructure::DependencyInjection::Container Generic DI container
+    # @see Stoplight::Wiring::LightFactory Factory that uses this container
+    # @api private
+    Container = Infrastructure::DependencyInjection::Container.define do
+      register(:config, Light::DefaultConfig)
+      register(:error_notifier, Default::ERROR_NOTIFIER)
+      register(:traffic_control, Default::TRAFFIC_CONTROL)
+      register(:traffic_recovery, Default::TRAFFIC_RECOVERY)
+
+      register(:data_store, Default::DATA_STORE) do |data_store|
+        FailSafeDataStore.wrap(
+          data_store:,
+          error_notifier: resolve(:error_notifier)
+        )
+      end
+
+      register(:notifiers, Default::NOTIFIERS) do |notifiers|
+        error_notifier = resolve(:error_notifier)
+        notifiers.map { |notifier| Wiring::FailSafeNotifier.wrap(notifier:, error_notifier:) }
+      end
+
+      factory(:green_run_strategy) do
+        Domain::Strategies::GreenRunStrategy.new(
+          config: resolve(:config),
+          request_tracker: resolve(:request_tracker)
+        )
+      end
+
+      factory(:yellow_run_strategy) do
+        Domain::Strategies::YellowRunStrategy.new(
+          config: resolve(:config),
+          data_store: resolve(:data_store),
+          notifiers: resolve(:notifiers),
+          request_tracker: resolve(:recovery_probe_tracker)
+        )
+      end
+
+      factory(:red_run_strategy) do
+        Domain::Strategies::RedRunStrategy.new(
+          config: resolve(:config)
+        )
+      end
+
+      factory(:request_tracker) do
+        Domain::Tracker::Request.new(
+          data_store: resolve(:data_store),
+          traffic_control: resolve(:traffic_control),
+          notifiers: resolve(:notifiers),
+          config: resolve(:config)
+        )
+      end
+
+      factory(:recovery_probe_tracker) do
+        Domain::Tracker::RecoveryProbe.new(
+          data_store: resolve(:data_store),
+          traffic_recovery: resolve(:traffic_recovery),
+          notifiers: resolve(:notifiers),
+          config: resolve(:config)
+        )
+      end
+    end
+  end
+end

data/lib/stoplight/wiring/default.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    module Default
+      COOL_OFF_TIME = 60.0
+
+      DATA_STORE = Infrastructure::DataStore::Memory.new
+
+      ERROR_NOTIFIER = ->(error) { warn error }
+
+      FORMATTER = Infrastructure::Notifier::Generic::DEFAULT_FORMATTER
+
+      NOTIFIERS = [Infrastructure::Notifier::IO.new($stderr)].freeze
+
+      THRESHOLD = 3
+      RECOVERY_THRESHOLD = 1
+
+      WINDOW_SIZE = nil
+
+      TRACKED_ERRORS = [StandardError].freeze
+      SKIPPED_ERRORS = [].freeze
+
+      TRAFFIC_CONTROL = Domain::TrafficControl::ConsecutiveErrors.new
+      TRAFFIC_RECOVERY = Domain::TrafficRecovery::ConsecutiveSuccesses.new
+    end
+  end
+end

data/lib/stoplight/{config/user_default_config.rb → wiring/default_configuration.rb}

@@ -1,29 +1,13 @@
 # frozen_string_literal: true
 
-require "forwardable"
-
 module Stoplight
-  module Config
-    # Represents user-defined default configuration for Stoplight.
-    #
-    # This class allows users to define default settings for various Stoplight
-    # parameters, such as cool-off time, data store, error notifier, and more.
-    # TODO: add evaluation/recovery strategy support
-    class UserDefaultConfig
-      extend Forwardable
-
+  module Wiring
+    # User-facing configuration interface
+    class DefaultConfiguration
       # @!attribute [w] cool_off_time
       #   @return [Integer, nil] The default cool-off time in seconds.
       attr_writer :cool_off_time
 
-      # @!attribute [w] error_notifier
-      #   @return [Proc, nil] The default error notifier (callable object).
-      attr_writer :error_notifier
-
-      # @!attribute [rw] notifiers
-      #   @return [Array<Stoplight::Notifier::Base>] The default list of notifiers.
-      attr_accessor :notifiers
-
       # @!attribute [w] threshold
       #   @return [Integer, Float, nil] The default failure threshold to trip the circuit breaker.
       attr_writer :threshold
@@ -44,14 +28,26 @@ module Stoplight
       #   @return [Array<Class>, nil] The default list of errors to skip.
       attr_writer :skipped_errors
 
-      # @!attribute [w] data_store
-      #   @return [Stoplight::DataStore::Base] The default data store instance.
-      attr_writer :data_store
+      # @!attribute [w] error_notifier
+      #   @return [Proc, nil] The default error notifier (callable object).
+      attr_writer :error_notifier
+
+      # @!attribute [rw] notifiers
+      #   @return [Array<Stoplight::Domain::StateTransitionNotifier>] The default list of notifiers.
+      attr_accessor :notifiers
+
+      # @!attribute [rw] data_store
+      #   @return [Stoplight::Domain::DataStore] The default data store instance.
+      attr_accessor :data_store
 
       # @!attribute [w] traffic_control
-      #   @return [Stoplight::TrafficControl::Base, Symbol, Hash] The traffic control strategy.
+      #   @return [Stoplight::Domain::TrafficControl::Base] The traffic control strategy.
       attr_writer :traffic_control
 
+      # @!attribute [w] traffic_recovery
+      #   @return [Stoplight::Domain::TrafficRecovery::Base] The traffic recovery strategy.
+      attr_writer :traffic_recovery
+
       def initialize
         # This allows users appending notifiers to the default list,
         # while still allowing them to override the default list.
@@ -65,21 +61,18 @@ module Stoplight
       def to_h
         {
           cool_off_time: @cool_off_time,
-          data_store: @data_store,
-          error_notifier: @error_notifier,
-          notifiers: @notifiers,
           threshold: @threshold,
           recovery_threshold: @recovery_threshold,
           window_size: @window_size,
           tracked_errors: @tracked_errors,
           skipped_errors: @skipped_errors,
-          traffic_control: @traffic_control
+          data_store: @data_store,
+          error_notifier: @error_notifier,
+          notifiers: @notifiers,
+          traffic_control: @traffic_control,
+          traffic_recovery: @traffic_recovery
         }.compact
       end
-
-      # @return [Boolean] True if the configuration hash is not empty, false otherwise.
-      # @api private
-      def_delegator :to_h, :any?
     end
   end
 end

data/lib/stoplight/wiring/default_factory_builder.rb

@@ -0,0 +1,25 @@
+# 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(Wiring::Container).with(**configuration.to_h)
+      end
+    end
+  end
+end