stoplight 5.6.0 → 5.8.0

data/lib/stoplight/wiring/notifier_factory.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    class NotifierFactory
+      class << self
+        # Wraps a notifier with fail-safe mechanisms.
+        #
+        # @param notifier [Stoplight::Domain::StateTransitionNotifier] The notifier to wrap.
+        # @param error_notifier [Proc] called when wrapped data store fails
+        # @return [Stoplight::Notifier::FailSafe] The original notifier if it is already
+        #   a +FailSafe+ instance, otherwise a new +FailSafe+ instance.
+        def create(notifier:, error_notifier:)
+          case notifier
+          in Infrastructure::Notifier::FailSafe if notifier.error_notifier == error_notifier
+            notifier
+          in Infrastructure::Notifier::FailSafe
+            Infrastructure::Notifier::FailSafe.new(notifier: notifier.notifier, error_notifier:)
+          else
+            Infrastructure::Notifier::FailSafe.new(notifier:, error_notifier:)
+          end
+        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