stoplight 5.8.3 → 6.0.0.rc2

data/lib/stoplight/wiring/light_factory.rb

@@ -2,126 +2,183 @@
 
 module Stoplight
   module Wiring
-    # Concrete factory for building +Stoplight::Light++ instances with full dependency wiring.
+    # Wires together all infrastructure components (trackers, strategies, storage
+    # backend) needed for a functioning circuit breaker.
     #
-    # This factory implements the +Stoplight::Domain::LightFactory+ protocol. It knows how to:
-    #   1. Parse and transform user-provided settings
-    #   2. Wire together all Light dependencies using a DI container
-    #   3. Validate configuration compatibility
-    #   4. Construct fully-functional Light instances
-    #
-    # @see Stoplight::Domain::LightFactory
-    # @see Stoplight()
     # @api private
-    #
     class LightFactory
-      def initialize(config:)
+      def initialize(system_id:, system_name:, config:, failover_system:, telemetry:)
+        @system_id = system_id
+        @system_name = system_name
+        @failover_system = failover_system
         @config = config
+
+        @clock = Infrastructure::SystemClock.new
+        @name = T.must(config.name)
+        @cool_off_time = config.cool_off_time
+
+        @data_store_config = config.data_store
+        @error_notifier = Infrastructure::FailSafe::ErrorNotifier.new(
+          error_notifier: config.error_notifier
+        )
+        @traffic_recovery = config.traffic_recovery
+        @traffic_control = config.traffic_control
+
+        @error_tracking_policy = Domain::ErrorTrackingPolicy.new(
+          tracked: config.tracked_errors,
+          skipped: config.skipped_errors
+        )
+
+        @emitter = Domain::Telemetry::Emitter.new(
+          bus: telemetry,
+          system_name: @system_name,
+          light_name: config.name,
+          clock: @clock,
+          error_notifier: @error_notifier
+        )
       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(
-          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)
+      def build
+        light = Stoplight::Domain::Light.new(
+          @name,
+          state_store:,
+          green_run_strategy:,
+          yellow_run_strategy:,
+          red_run_strategy:,
+          lock_control:,
+          error_tracking_policy: @error_tracking_policy
         )
+
+        @emitter.emit(Domain::Telemetry::LightRegistered) do
+          Domain::Telemetry::LightRegistered.new(settings: telemetry_settings)
+        end
+
+        light
       end
 
-      # Builds a fully-configured Light instance.
-      #
-      # The method resolves all dependencies from the container and constructs a Light that's
-      # ready to use. The Light is injected with a reference to this factory, allowing the
-      # +Stoplight::Light#with+ method to work for reconfiguration.
-      #
-      # @return [Stoplight::Light] Configured circuit breaker
-      # @raise [Stoplight::Error::ConfigurationError] If configuration is invalid
-      #
-      # @example
-      #   factory = Stoplight::Wiring::LightFactory.new(container)
-      #   light = factory.build
-      #
-      #   # Light is ready to use
-      #   light.run { api_call }
+      def state_store = storage_set.state_store
+      def metrics_store = storage_set.metrics_store
+      def lock_control = Domain::LockControl.new(state_store:, emitter: @emitter)
+      def recovery_metrics_store = storage_set.recovery_metrics_store
 
-      def build
-        light_builder(config:).build
+      private
+
+      attr_reader :data_store_config
+      attr_reader :error_notifier
+      attr_reader :clock
+      attr_reader :traffic_control
+      attr_reader :traffic_recovery
+      attr_reader :config
+      attr_reader :system_name
+
+      def recovery_lock_store = storage_set.recovery_lock_store
+      def storage_scripting = Infrastructure::Redis::Storage::Scripting.new(redis:)
+      def failover_system = T.must(@failover_system)
+
+      def key_space
+        @key_space ||= case data_store_config
+        when DataStore::Redis
+          # We use keys like +stoplight:version:system_id:{light_id}:metrics+ prefixes,
+          # Putting +liht_id+ into curly braces make it a Redis Cluster hash-tag - this is a  segment
+          # for slot colocation.
+          data_store_config.key_space.join(@system_id, "{#{@config.id}}")
+        else
+          raise T.absurd(data_store_config)
+        end
       end
 
-      def ==(other)
-        other.is_a?(self.class) && other.config == config
+      def storage_set
+        @storage_set ||= StorageSetBuilder.new(backend: build_backend, windowed: !config.window_size.nil?).build
       end
 
-      alias_method :eql?, :==
-
-      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
+      def request_tracker
+        Domain::Tracker::Request.new(traffic_control:, config:, metrics_store:, state_store:, emitter: @emitter)
       end
 
-      def hash
-        [self.class, config].hash
+      def recovery_probe_tracker
+        Domain::Tracker::RecoveryProbe.new(
+          traffic_recovery:,
+          config:,
+          metrics_store: recovery_metrics_store,
+          state_store:,
+          emitter: @emitter
+        )
       end
 
-      protected
+      def green_run_strategy
+        Domain::Strategies::GreenRunStrategy.new(
+          request_tracker:,
+          clock:,
+          run_recorder: run_recorder(Color::GREEN)
+        )
+      end
 
-      attr_reader :config
+      def yellow_run_strategy
+        Domain::Strategies::YellowRunStrategy.new(
+          name: @name,
+          request_tracker: recovery_probe_tracker,
+          state_store:,
+          metrics_store:,
+          recovery_lock_store:,
+          config: @config,
+          clock:,
+          run_recorder: run_recorder(Color::YELLOW),
+          emitter: @emitter
+        )
+      end
 
-      private
+      def red_run_strategy
+        Domain::Strategies::RedRunStrategy.new(
+          name: @name,
+          cool_off_time: @cool_off_time,
+          run_recorder: run_recorder(Color::RED)
+        )
+      end
 
-      def light_builder(config:)
-        LightBuilder.new(config:, factory: light_factory)
+      def run_recorder(color)
+        Domain::Telemetry::RunRecorder.new(emitter: @emitter, color:)
       end
 
-      def light_factory = self
+      def telemetry_settings
+        Domain::Telemetry::Settings.new(
+          cool_off_time: @config.cool_off_time,
+          threshold: @config.threshold,
+          recovery_threshold: @config.recovery_threshold,
+          window_size: @config.window_size,
+          tracked_errors: @config.tracked_errors.map { |matcher| Domain::MatcherValidator.call(matcher) },
+          skipped_errors: @config.skipped_errors.map { |matcher| Domain::MatcherValidator.call(matcher) },
+          traffic_control: @config.traffic_control.name,
+          traffic_recovery: @config.traffic_recovery.name,
+          # No strategy accepts constructor params yet; placeholder for forward compatibility.
+          traffic_control_params: {},
+          traffic_recovery_params: {}
+        )
+      end
+
+      def redis
+        case data_store_config
+        when DataStore::Redis
+          data_store_config.redis
+        else
+          raise T.absurd(data_store_config)
+        end
+      end
+
+      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: create_circuit_breaker("redis")
+          )
+        end
+      end
+
+      def create_circuit_breaker(name)
+        failover_system.register(name)
+      end
     end
   end
 end

data/lib/stoplight/wiring/notifier_bridge.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    # Subscribes the legacy, user-facing +Notifier+ collaborators to the telemetry bus, so
+    # +Domain::Light+'s collaborators never call notifiers directly.
+    #
+    # @api private
+    class NotifierBridge
+      def initialize(notifiers:)
+        @notifiers = notifiers
+      end
+
+      def subscribe(bus)
+        bus.subscribe(Domain::Telemetry::TrafficBreached) { |envelope| notify(envelope, error: envelope.payload.failure&.exception) }
+        bus.subscribe(Domain::Telemetry::RecoveryStarted) { |envelope| notify(envelope, error: nil) }
+        bus.subscribe(Domain::Telemetry::RecoverySucceeded) { |envelope| notify(envelope, error: nil) }
+        bus.subscribe(Domain::Telemetry::RecoveryFailed) { |envelope| notify(envelope, error: envelope.payload.failure&.exception) }
+      end
+
+      private
+
+      def notify(envelope, error:)
+        info = Domain::LightInfo.new(name: envelope.light_name)
+        payload = envelope.payload
+
+        @notifiers.each do |notifier|
+          notifier.notify(info, payload.from_color, payload.to_color, error)
+        end
+      end
+    end
+  end
+end

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

@@ -17,7 +17,7 @@ module Stoplight
       #   backend = Redis::Backend.new(
       #     redis: redis_connection,
       #     scripting: Scripting.new(redis:),
-      #     key_space: KeySpace.build(system_name: "payments", light_name: "stripe"),
+      #     key_space:,
       #     config: light_config,
       #     error_notifier: ->(e) { Logger.error(e) },
       #     failover_light: Stoplight("redis-failover"),

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Wiring
+    class System
+      # Only for admin panel use.
+      class Storage
+        def initialize(system_id:, system_name:, failover_system:, telemetry:)
+          @system_id = system_id
+          @system_name = system_name
+          @failover_system = failover_system
+          @factories = {}
+          @telemetry = telemetry
+        end
+
+        def recovery_metrics_snapshot(config)
+          recovery_metrics_store(config).metrics_snapshot
+        end
+
+        def state_snapshot(config)
+          state_store(config).state_snapshot
+        end
+
+        def metrics_snapshot(config)
+          metrics_store(config).metrics_snapshot
+        end
+
+        def delete(config)
+          state_store(config).clear
+          metrics_store(config).clear
+        end
+
+        def lock(config, color)
+          lock_control(config).lock(color)
+        end
+
+        def unlock(config)
+          lock_control(config).unlock
+        end
+
+        private def recovery_metrics_store(config)
+          light_factory(config).recovery_metrics_store
+        end
+
+        private def state_store(config)
+          light_factory(config).state_store
+        end
+
+        private def metrics_store(config)
+          light_factory(config).metrics_store
+        end
+
+        private def lock_control(config)
+          light_factory(config).lock_control
+        end
+
+        private def light_factory(config)
+          @factories[config] ||= LightFactory.new(
+            system_id: @system_id,
+            system_name: @system_name,
+            config:,
+            failover_system: @failover_system,
+            telemetry: @telemetry
+          )
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/wiring/system.rb

@@ -4,7 +4,6 @@ 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
@@ -13,71 +12,97 @@ module Stoplight
     # This prevents subtle bugs where circuits silently interfere with each other.
     #
     # @example Basic usage
-    #   billing = Stoplight.system(:billing,
+    #   billing = Stoplight.register_system(
+    #     "Billing",
     #     data_store: billing_redis,
     #     threshold: 5,
     #     window_size: 300
     #   )
     #
-    #   billing.light("stripe")
-    #   billing.light("paypal")
+    #   billing.register("stripe")
+    #   billing.register("paypal")
+    #
+    #   billing.light("stripe").run { ... }
+    #   billing.light("paypal").run { ... }
     #
     # @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)
+    #   tenant_a = Stoplight.register_system("Tenant A", data_store: tenant_a_redis)
+    #   tenant_b = Stoplight.register_system("Tenant B", data_store: tenant_b_redis)
     #
     #   # Same circuit name, completely isolated
-    #   tenant_a.light("api")
-    #   tenant_b.light("api")
+    #   tenant_a.register("api")
+    #   tenant_b.register("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
+    #   system = Stoplight.register_system("Payments", threshold: 3, cool_off_time: 600)
     #
-    # @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.
+    #   system.register("stripe")                # Inherits threshold: 3
+    #   system.register("paypal", threshold: 5)  # Overrides threshold
     #
-    # @note Light instances are cached within the system. Calling {#light} with
-    #   the same name returns the cached instance.
-    #
-    # @api private
+    # @note Light instances are cached within the system once {#register}ed. {#light}
+    #   returns that cached instance and raises +Stoplight::Error::UnregisteredLightError+
+    #   if the name was never registered.
     class System
+      REGISTRATION_FRAME_LIMIT = 5
+      private_constant :REGISTRATION_FRAME_LIMIT
+
       attr_reader :name
-      # @!attribute system_config
-      #   @api private
-      attr_reader :system_config
+      # @api private
+      attr_reader :config
 
-      def initialize(config:)
+      # Returns the consumer (subscribe-only) side of the telemetry bus.
+      def telemetry
+        Domain::Telemetry::Consumer.new(@telemetry)
+      end
+
+      # @param failover_system is a system used to create lights that protects components
+      #   of this system. For example if your system uses Redis data store, or notifiers that
+      #   communicate with external systems, they could go off. Failover system hosts
+      #   all the circuit breakers that are needed to protect these dependencies from failing.
+      #   Failover system itself never uses external dependencies and therefore does not need
+      #   external failover.
+      def initialize(config:, failover_system:, registry:)
         @name = config.name
-        @system_config = config
+        @config = config
         @lights = Concurrent::Map.new
+        @failover_system = failover_system
+        @registry = registry
+        @telemetry = Domain::Telemetry::Bus.new(error_notifier: config.error_notifier)
+
+        unless config.notifiers.empty?
+          NotifierBridge.new(notifiers: wrapped_notifiers).subscribe(@telemetry)
+        end
       end
 
-      # Creates or retrieves a light.
+      def persistent?
+        case @config.data_store
+        when DataStore::Redis
+          true
+        when DataStore::Memory
+          false
+        else
+          raise T.absurd(@config.data_store)
+        end
+      end
+
+      # Registers and returns a light.
       #
-      # If a light with this name already exists, returns the cached instance.
+      # If a light with this name already exists, returns it.
       # 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 Register a light
+      #   system.register("stripe", threshold: 5, window_size: 60)
+      #   system.light("stripe") #=> returns named light
       #
       # @example Configuration conflict
-      #   system.light("api", threshold: 5)
-      #   system.light("api", threshold: 10)  # Raises ConfigurationError
+      #   system.register("api", threshold: 5)
+      #   system.register("api", threshold: 10)  # Raises ConfigurationError
       #
       # @note Thread-safe: multiple threads can safely call this method concurrently
       #
-      def light(
+      def register(
         name,
         cool_off_time: T.undefined,
         threshold: T.undefined,
@@ -88,7 +113,7 @@ module Stoplight
         traffic_control: T.undefined,
         traffic_recovery: T.undefined
       )
-        light_config = ConfigurationDsl.new(
+        light_dsl = LightConfigurationDsl.new(
           name:,
           cool_off_time:,
           threshold:,
@@ -98,32 +123,76 @@ module Stoplight
           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]
+        )
+        config_digest = light_dsl.digest
+
+        light, existing_digest, existing_backtrace = @lights[name] || begin
+          registered_at = ExternalCaller.backtrace.first(REGISTRATION_FRAME_LIMIT)
+          config = light_dsl.configure!(@config)
+          @lights.compute_if_absent(name) do
+            built = LightFactory.new(
+              system_id: @config.id,
+              system_name: @name, config:,
+              failover_system: @failover_system,
+              telemetry: @telemetry
+            ).build
+            @registry.register(config)
+            [built, config_digest, registered_at]
           end
         end
+
+        if config_digest != existing_digest
+          original_site = existing_backtrace.map { |frame| "  #{frame}" }.join("\n")
+
+          raise Stoplight::Error::ConfigurationError, <<~MSG, ExternalCaller.backtrace
+            Light `#{name}` already registered with different configuration.
+
+            Originally registered at:
+            #{original_site}
+
+            Lights must have consistent configuration across all call sites.
+          MSG
+        end
+
         light
       end
 
+      # @raise [Stoplight::Error::UnregisteredLightError] if no light was registered under +name+
+      def light(name)
+        @lights[name]&.first || raise(Stoplight::Error::UnregisteredLightError, <<~MSG)
+          Light `#{name}` was never registered on system `#{@name}`.
+          Call `.register(#{name.inspect}, ...)` at boot before using it.
+        MSG
+      end
+
+      # @api private
+      def __stoplight__storage
+        Storage.new(
+          system_id: @config.id,
+          system_name: @name,
+          failover_system: T.must(@failover_system), # works only with redis ds
+          telemetry: @telemetry
+        )
+      end
+
+      # @api private
+      def __stoplight__registry
+        @registry
+      end
+
       private
 
-      attr_reader :lights
+      def wrapped_notifiers
+        error_notifier = Infrastructure::FailSafe::ErrorNotifier.new(error_notifier: @config.error_notifier)
+
+        @config.notifiers.map do |notifier|
+          Infrastructure::Notifier::FailSafe.new(
+            notifier:,
+            error_notifier:,
+            circuit_breaker: T.must(@failover_system).register("notifier:#{notifier.class.name}")
+          )
+        end
+      end
     end
   end
 end