stoplight 5.7.0 → 5.8.2

data/lib/stoplight/wiring/light_factory.rb

@@ -13,39 +13,42 @@ module Stoplight
     # @see Stoplight::Domain::LightFactory
     # @see Stoplight()
     # @api private
-
-    class LightFactory < Domain::LightFactory
-      DEPENDENCY_KEYS = %i[data_store traffic_recovery traffic_control notifiers error_notifier].freeze
-      private_constant :DEPENDENCY_KEYS
-
-      CONFIG_KEYS = Domain::Config.members.freeze
-      private_constant :CONFIG_KEYS
-
-      # @!attribute [r] settings
-      #   @return [Hash]
-      protected attr_reader :settings
-
-      def initialize(settings = {})
-        @settings = settings
-
-        validate_settings!
-      end
-
-      private def validate_settings!
-        recognized = CONFIG_KEYS + DEPENDENCY_KEYS
-        unknown = settings.keys - recognized
-
-        return if unknown.empty?
-
-        raise ArgumentError, "Unknown settings: #{unknown.join(", ")}", caller(2)
+    #
+    class LightFactory
+      def initialize(config:)
+        @config = config
       end
 
-      # @param settings [Hash] Settings to override in the new factory
-      #   @see Stoplight()
-      # @return [Stoplight::Wiring::LightFactory]
-      # @see Stoplight()
-      def with(**settings)
-        self.class.new(self.settings.merge(settings))
+      def with(
+        name: T.undefined,
+        cool_off_time: T.undefined,
+        threshold: T.undefined,
+        recovery_threshold: T.undefined,
+        window_size: T.undefined,
+        tracked_errors: T.undefined,
+        skipped_errors: T.undefined,
+        data_store: T.undefined,
+        error_notifier: T.undefined,
+        notifiers: T.undefined,
+        traffic_control: T.undefined,
+        traffic_recovery: T.undefined
+      )
+        self.class.new(
+          config: ConfigurationDsl.new(
+            name:,
+            cool_off_time:,
+            threshold:,
+            recovery_threshold:,
+            window_size:,
+            tracked_errors:,
+            skipped_errors:,
+            traffic_control:,
+            traffic_recovery:,
+            error_notifier:,
+            data_store:,
+            notifiers:
+          ).configure!(config)
+        )
       end
 
       # Builds a fully-configured Light instance.
@@ -65,37 +68,60 @@ module Stoplight
       #   light.run { api_call }
 
       def build
-        config_settings = settings.slice(*CONFIG_KEYS)
-        dependency_settings = settings.slice(*DEPENDENCY_KEYS)
+        light_builder(config:).build
+      end
 
-        config, dependencies = ConfigurationPipeline.process(
-          config_settings,
-          dependency_settings
-        )
-        LightBuilder.new(factory: self, config:, **dependencies).build
+      def ==(other)
+        other.is_a?(self.class) && other.config == config
       end
 
-      # @return [Stoplight::Error::ConfigurationError]
-      def validate_configuration!
-        config_settings = settings.slice(*CONFIG_KEYS)
-        dependency_settings = settings.slice(*DEPENDENCY_KEYS)
+      alias_method :eql?, :==
 
-        ConfigurationPipeline.process(
-          config_settings,
-          dependency_settings
-        )
-        nil
+      def build_with(
+        name: T.undefined,
+        cool_off_time: T.undefined,
+        threshold: T.undefined,
+        recovery_threshold: T.undefined,
+        window_size: T.undefined,
+        tracked_errors: T.undefined,
+        skipped_errors: T.undefined,
+        data_store: T.undefined,
+        error_notifier: T.undefined,
+        notifiers: T.undefined,
+        traffic_control: T.undefined,
+        traffic_recovery: T.undefined
+      )
+        with(
+          name:,
+          cool_off_time:,
+          threshold:,
+          recovery_threshold:,
+          window_size:,
+          tracked_errors:,
+          skipped_errors:,
+          data_store:,
+          error_notifier:,
+          notifiers:,
+          traffic_control:,
+          traffic_recovery:
+        ).build
       end
 
-      def ==(other)
-        other.is_a?(self.class) && other.settings == settings
+      def hash
+        [self.class, config].hash
       end
 
-      alias_method :eql?, :==
+      protected
 
-      def hash
-        [self.class, settings].hash
+      attr_reader :config
+
+      private
+
+      def light_builder(config:)
+        LightBuilder.new(config:, factory: light_factory)
       end
+
+      def light_factory = self
     end
   end
 end

data/lib/stoplight/wiring/memory/backend.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    module Memory
+      # In-memory storage backend for single-process deployments.
+      #
+      # All storage components use thread-safe in-memory data structures.
+      # State is not shared across processes and is lost on restart.
+      #
+      # Memory backend is also used as the fallback layer for Redis backend
+      # when Redis is unavailable.
+      #
+      # @example
+      #   backend = Memory::Backend.new(clock: SystemClock.new, config:)
+      #   backend.state_store #=> Memory::Storage::State
+      #
+      # @api private
+      class Backend < DataStoreBackend
+        def initialize(clock:, config:)
+          @clock = clock
+          @config = config
+        end
+
+        def state_store
+          @state_store ||= Infrastructure::Memory::Storage::State.new(
+            clock: @clock,
+            cool_off_time: @config.cool_off_time
+          )
+        end
+
+        def recovery_lock_store
+          @recovery_lock_store ||= Infrastructure::Memory::Storage::RecoveryLock.new
+        end
+
+        def recovery_metrics_store
+          @recovery_metrics_store ||= Infrastructure::Memory::Storage::RecoveryMetrics.new(
+            clock: @clock
+          )
+        end
+
+        def windowed_metrics_store
+          @windowed_metrics_store ||= Infrastructure::Memory::Storage::WindowMetrics.new(
+            window_size: T.must(@config.window_size),
+            clock: @clock
+          )
+        end
+
+        def unbounded_metrics_store
+          @unbounded_metrics_store ||= Infrastructure::Memory::Storage::UnboundedMetrics.new(
+            clock: @clock
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    module Redis
+      # Redis storage backend with automatic failover to in-memory storage.
+      #
+      # Every storage component is wrapped in a FailSafe decorator that catches
+      # Redis connection errors and falls back to a Memory backend. This ensures
+      # circuit breakers remain functional even when Redis is unavailable.
+      #
+      # The failover behavior is coordinated through a dedicated circuit breaker
+      # (`failover_light`) that prevents repeated Redis connection attempts during
+      # an outage.
+      #
+      # @example
+      #   backend = Redis::Backend.new(
+      #     redis: redis_connection,
+      #     scripting: Scripting.new(redis:),
+      #     key_space: KeySpace.build(system_name: "payments", light_name: "stripe"),
+      #     config: light_config,
+      #     error_notifier: ->(e) { Logger.error(e) },
+      #     failover_light: Stoplight("redis-failover"),
+      #     clock: SystemClock.new
+      #   )
+      #
+      #   backend.state_store #=> FailSafe::State wrapping Redis::State
+      #
+      # @api private
+      class Backend < DataStoreBackend
+        def initialize(redis:, scripting:, key_space:, config:, error_notifier:, failover_light:, clock:)
+          @redis = redis
+          @scripting = scripting
+          @key_space = key_space
+          @clock = clock
+          @config = config
+          @error_notifier = error_notifier
+          @failover_light = failover_light
+          @memory_fallback = Memory::Backend.new(clock:, config:)
+        end
+
+        def state_store
+          @state_store ||= Infrastructure::FailSafe::Storage::State.new(
+            primary_store: Infrastructure::Redis::Storage::State.new(
+              redis: @redis,
+              scripting: @scripting,
+              key_space: @key_space,
+              cool_off_time: @config.cool_off_time,
+              clock: @clock
+            ),
+            error_notifier: @error_notifier,
+            failover_store: @memory_fallback.state_store,
+            circuit_breaker: @failover_light
+          )
+        end
+
+        def recovery_lock_store
+          @recovery_lock_store ||= Infrastructure::FailSafe::Storage::RecoveryLock.new(
+            primary_store: Infrastructure::Redis::Storage::RecoveryLock.new(
+              config: @config, # TODO: pass cool_off_time directly
+              redis: @redis,
+              scripting: @scripting,
+              key_space: @key_space
+            ),
+            error_notifier: @error_notifier,
+            failover_store: @memory_fallback.recovery_lock_store,
+            circuit_breaker: @failover_light
+          )
+        end
+
+        def recovery_metrics_store
+          @recovery_metrics_store ||= Infrastructure::FailSafe::Storage::Metrics.new(
+            error_notifier: @error_notifier,
+            primary_store: Infrastructure::Redis::Storage::RecoveryMetrics.new(
+              clock: @clock,
+              redis: @redis,
+              scripting: @scripting,
+              key_space: @key_space
+            ),
+            failover_store: @memory_fallback.recovery_metrics_store,
+            circuit_breaker: @failover_light
+          )
+        end
+
+        def windowed_metrics_store
+          @windowed_metrics_store ||= Infrastructure::FailSafe::Storage::Metrics.new(
+            error_notifier: @error_notifier,
+            primary_store: Infrastructure::Redis::Storage::WindowMetrics.new(
+              config: @config, # TODO: pass window size directly
+              redis: @redis,
+              scripting: @scripting,
+              clock: @clock,
+              key_space: @key_space
+            ),
+            failover_store: @memory_fallback.windowed_metrics_store,
+            circuit_breaker: @failover_light
+          )
+        end
+
+        def unbounded_metrics_store
+          @unbounded_metrics_store ||= Infrastructure::FailSafe::Storage::Metrics.new(
+            error_notifier: @error_notifier,
+            primary_store: Infrastructure::Redis::Storage::UnboundedMetrics.new(
+              clock: @clock,
+              redis: @redis,
+              scripting: @scripting,
+              key_space: @key_space
+            ),
+            failover_store: @memory_fallback.unbounded_metrics_store,
+            circuit_breaker: @failover_light
+          )
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/wiring/storage_set.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    StorageSet = Data.define(
+      :metrics_store,
+      :recovery_metrics_store,
+      :state_store,
+      :recovery_lock_store
+    )
+  end
+end

data/lib/stoplight/wiring/storage_set_builder.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    # Assembles a StorageSet from a backend, selecting windowed or unbounded metrics.
+    #
+    # StorageSetBuilder is the single point where the windowed/unbounded decision
+    # is made. All other storage components (state, recovery lock, recovery metrics)
+    # are backend-specific but mode-independent.
+    #
+    # @example Windowed metrics (error rate tracking)
+    #   builder = StorageSetBuilder.new(backend: redis_backend, windowed: true)
+    #   storage = builder.build
+    #   storage.metrics_store #=> FailSafe<WindowMetrics>
+    #
+    # @example Unbounded metrics (consecutive error tracking)
+    #   builder = StorageSetBuilder.new(backend: memory_backend, windowed: false)
+    #   storage = builder.build
+    #   storage.metrics_store #=> UnboundedMetrics
+    #
+    # @see DataStoreBackend
+    # @see StorageSet
+    # @api private
+    class StorageSetBuilder
+      attr_reader :backend
+      attr_reader :windowed
+
+      def initialize(backend:, windowed:)
+        @backend = backend
+        @windowed = windowed
+      end
+
+      def build
+        StorageSet.new(
+          metrics_store:,
+          recovery_metrics_store: backend.recovery_metrics_store,
+          state_store: backend.state_store,
+          recovery_lock_store: backend.recovery_lock_store
+        )
+      end
+
+      private def metrics_store
+        if windowed
+          backend.windowed_metrics_store
+        else
+          backend.unbounded_metrics_store
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/wiring/system/light_builder.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    class System
+      class LightBuilder < Wiring::LightBuilder
+        def initialize(system:, config:, factory:)
+          @system = system
+
+          super(config:, factory:)
+        end
+
+        def key_space = @key_space ||= Infrastructure::Redis::Storage::KeySpace.build(
+          system_name: system.name,
+          light_name: config.name
+        )
+
+        def storage_set
+          @storage_set ||= StorageSetBuilder.new(backend: build_backend, windowed: !config.window_size.nil?).build
+        end
+
+        private
+
+        attr_reader :system
+
+        def state_store = storage_set.state_store
+        def recovery_lock_store = storage_set.recovery_lock_store
+        def recovery_metrics_store = storage_set.recovery_metrics_store
+        def metrics_store = storage_set.metrics_store
+        def storage_scripting = Infrastructure::Redis::Storage::Scripting.new(redis:)
+        def failover_system = @failover_system ||= Stoplight.__stoplight__system("failover-#{system.name}")
+
+        def build_backend
+          case data_store_config
+          in DataStore::Memory
+            Memory::Backend.new(clock:, config:)
+          in DataStore::Redis
+            Redis::Backend.new(
+              redis:, scripting: storage_scripting, key_space:, clock:, config:, error_notifier:,
+              failover_light: failover_system.light("redis")
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    class System
+      class LightFactory < Wiring::LightFactory
+        attr_reader :system
+
+        def initialize(system:, config:)
+          @system = system
+
+          super(config:)
+        end
+
+        def with(
+          name: T.undefined,
+          cool_off_time: T.undefined,
+          threshold: T.undefined,
+          recovery_threshold: T.undefined,
+          window_size: T.undefined,
+          tracked_errors: T.undefined,
+          skipped_errors: T.undefined,
+          data_store: T.undefined,
+          error_notifier: T.undefined,
+          notifiers: T.undefined,
+          traffic_control: T.undefined,
+          traffic_recovery: T.undefined
+        )
+          self.class.new(
+            system:,
+            config: ConfigurationDsl.new(
+              cool_off_time:,
+              threshold:,
+              recovery_threshold:,
+              window_size:,
+              tracked_errors:,
+              skipped_errors:,
+              traffic_control:,
+              traffic_recovery:,
+              error_notifier:,
+              data_store:,
+              notifiers:
+            ).configure!(config)
+          )
+        end
+
+        class InternalLightFactory < Wiring::LightFactory
+          def initialize
+          end
+
+          def with(**untyped) # steep:ignore
+            raise NotImplementedError, "You're not allowed to extend system lights"
+          end
+        end
+
+        private def light_builder(config:)
+          System::LightBuilder.new(system:, factory: light_factory, config:)
+        end
+
+        private def light_factory = InternalLightFactory.new
+      end
+    end
+  end
+end

data/lib/stoplight/wiring/system.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+
+module Stoplight
+  module Wiring
+    # 🚧UNDER CONSTRUCTION 🚧
+    # System provides namespace isolation and shared configuration for related circuits.
+    #
+    # Systems enforce configuration consistency within their scope - creating the same
+    # circuit name with different settings raises +Stoplight::Error::ConfigurationError+.
+    #
+    # This prevents subtle bugs where circuits silently interfere with each other.
+    #
+    # @example Basic usage
+    #   billing = Stoplight.system(:billing,
+    #     data_store: billing_redis,
+    #     threshold: 5,
+    #     window_size: 300
+    #   )
+    #
+    #   billing.light("stripe")
+    #   billing.light("paypal")
+    #
+    # @example Multi-tenancy
+    #   tenant_a = Stoplight.system(:tenant_a, data_store: tenant_a_redis)
+    #   tenant_b = Stoplight.system(:tenant_b, data_store: tenant_b_redis)
+    #
+    #   # Same circuit name, completely isolated
+    #   tenant_a.light("api")
+    #   tenant_b.light("api")
+    #
+    # @example Configuration inheritance
+    #   system = Stoplight.system(:payments, threshold: 3, cool_off_time: 600)
+    #
+    #   system.light("stripe")                # Inherits threshold: 3
+    #   system.light("paypal", threshold: 5)  # Overrides threshold
+    #
+    # @note System configuration objects (data_store, notifiers) should be defined
+    #   as constants and reused, not created inline. This ensures configuration
+    #   matching works correctly across multiple system references.
+    #
+    # @note Light instances are cached within the system. Calling {#light} with
+    #   the same name returns the cached instance.
+    #
+    # @api private
+    class System
+      attr_reader :name
+      # @!attribute system_config
+      #   @api private
+      attr_reader :system_config
+
+      def initialize(config:)
+        @name = config.name
+        @system_config = config
+        @lights = Concurrent::Map.new
+      end
+
+      # Creates or retrieves a light.
+      #
+      # If a light with this name already exists, returns the cached instance.
+      # If settings differ from the existing light, raises +Stoplight::Error::ConfigurationError+.
+      #
+      #
+      # @raise [Stoplight::Error::ConfigurationError] if light exists with different settings
+      #
+      # @example Create a light
+      #   light = system.light("stripe", threshold: 5, window_size: 60)
+      #
+      # @example Retrieve existing light - both return cached light
+      #   light = system.light("stripe", threshold: 5, window_size: 60)
+      #   light = system.light("stripe")
+      #
+      # @example Configuration conflict
+      #   system.light("api", threshold: 5)
+      #   system.light("api", threshold: 10)  # Raises ConfigurationError
+      #
+      # @note Thread-safe: multiple threads can safely call this method concurrently
+      #
+      def light(
+        name,
+        cool_off_time: T.undefined,
+        threshold: T.undefined,
+        recovery_threshold: T.undefined,
+        window_size: T.undefined,
+        tracked_errors: T.undefined,
+        skipped_errors: T.undefined,
+        traffic_control: T.undefined,
+        traffic_recovery: T.undefined
+      )
+        light_config = ConfigurationDsl.new(
+          name:,
+          cool_off_time:,
+          threshold:,
+          recovery_threshold:,
+          window_size:,
+          tracked_errors:,
+          skipped_errors:,
+          traffic_control:,
+          traffic_recovery:
+        ).configure!(system_config)
+
+        light, _ = lights.compute(name) do |existing|
+          if existing
+            existing_light, existing_config = existing
+            if light_config == existing_config
+              [existing_light, existing_config]
+            else
+              raise Stoplight::Error::ConfigurationError, <<~MSG
+                Light name `#{name}` reused with different settings:
+                  existing settings: #{existing_config}
+                  new settings:      #{light_config}
+
+                You cannot use the same light name with different settings.
+              MSG
+            end
+          else
+            [LightFactory.new(system: self, config: light_config).build, light_config]
+          end
+        end
+        light
+      end
+
+      private
+
+      attr_reader :lights
+    end
+  end
+end