stoplight 5.7.0 → 5.8.2

data/{lib/stoplight/domain/light_factory.rb → sig/_private/stoplight/domain/ports/light_factory.rbs}

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module Stoplight
   module Domain
     # Abstract factory protocol for building +Stoplight::Light+ instances.
@@ -17,39 +15,36 @@ module Stoplight
     # - Different factory implementations can be swapped (code, database-configured, etc.)
     # - Dependency direction is preserved (Application → Domain, not Domain → Application)
     #
-    # @abstract Subclasses must implement +#with+ and +#build+
-    # @api private
-    class LightFactory
+    interface _LightFactory
       # Creates a new factory with modified settings.
       #
       # This method must return a NEW factory instance - it should not
       # modify the current factory. The new factory should inherit all
       # configuration from the current factory, with the provided
       # settings overriding specific values.
-      #
-      # @param settings [Hash] Configuration and dependency overrides
-      # @return [Stoplight::Domain::LightFactory] New factory with updated settings
-      # @raise [NotImplementedError] Must be implemented by subclass
-      # @abstract
-      # :nocov:
-      def with(**settings)
-        raise NotImplementedError
-      end
+      def with: (
+          ?name: optional[String],
+          ?cool_off_time: optional[duration],
+          ?threshold: optional[percentage | Integer],
+          ?recovery_threshold: optional[Integer],
+          ?window_size: optional[duration?],
+          ?tracked_errors: optional[Array[_ExceptionMatcher] | _ExceptionMatcher],
+          ?skipped_errors: optional[Array[_ExceptionMatcher] | _ExceptionMatcher],
+          ?error_notifier: optional[error_notifier],
+          ?notifiers: optional[Array[state_transition_notifier]],
+          ?data_store: optional[data_store],
+          ?traffic_control: optional[traffic_control],
+          ?traffic_recovery: optional[traffic_recovery],
+      ) -> _LightFactory
 
-      # Builds a +Stoplight::Light+ instance with the current configuration.
+      # Builds a Light instance with the current configuration.
       #
       # This method must construct a fully-wired Light with all required
       # dependencies (strategies, data store, notifiers, etc.). The Light
       # should be ready to use immediately after construction.
       #
-      # @return [Stoplight::Light] Configured circuit breaker instance
-      # @raise [NotImplementedError] Must be implemented by subclass
       # @raise [Stoplight::Error::ConfigurationError] If configuration is invalid
-      # @abstract
-      def build
-        raise NotImplementedError
-      end
-      # :nocov:
+      def build: -> Light
 
       # Convenience method to configure and build in one operation.
       #
@@ -57,9 +52,6 @@ module Stoplight
       # useful when you want to create a customized Light without keeping
       # a reference to the intermediate factory.
       #
-      # @param settings [Hash] Settings to override before building
-      # @return [Stoplight::Light] Configured circuit breaker instance
-      #
       # @example Usage
       #   # Instead of:
       #   new_factory = factory.with(threshold: 10)
@@ -67,9 +59,22 @@ module Stoplight
       #
       #   # You can do:
       #   light = factory.build_with(threshold: 10)
-      def build_with(**settings)
-        with(**settings).build
-      end
+      def build_with: (
+          ?name: optional[String],
+          ?cool_off_time: optional[duration],
+          ?threshold: optional[percentage | Integer],
+          ?recovery_threshold: optional[Integer],
+          ?window_size: optional[duration?],
+          ?tracked_errors: optional[Array[_ExceptionMatcher] | _ExceptionMatcher],
+          ?skipped_errors: optional[Array[_ExceptionMatcher] | _ExceptionMatcher],
+          ?error_notifier: optional[error_notifier],
+          ?notifiers: optional[Array[state_transition_notifier]],
+          ?data_store: optional[data_store],
+          ?traffic_control: optional[traffic_control],
+          ?traffic_recovery: optional[traffic_recovery],
+      ) -> Light
+
+      def ==: (untyped) -> bool
     end
   end
 end

data/sig/_private/stoplight/domain/ports/metrics_store.rbs

@@ -0,0 +1,29 @@
+module Stoplight
+  module Domain
+    # 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.
+    #
+    interface _MetricsStore
+      # Retrieves a snapshot of current metrics for decision-making.
+      def metrics_snapshot: () -> Domain::MetricsSnapshot
+
+      # Records a successful circuit breaker execution
+      def record_success: () -> void
+
+      # Records a failed circuit breaker execution
+      def record_failure: (StandardError error) -> void
+
+      # Clears all metrics for this circuit
+      def clear: () -> void
+    end
+  end
+end

data/sig/_private/stoplight/domain/ports/recovery_lock_store.rbs

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    # 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)
+    #
+    # @see Stoplight::Domain::Strategies::YellowRunStrategy
+    interface _RecoveryLockStore
+      # 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
+      #   - +RecoveryLockToken+: Lock acquired, caller should send probe
+      #   - +nil+: Lock unavailable, another instance is probing
+      #
+      def acquire_lock: -> Storage::RecoveryLockToken?
+
+      # 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 The token returned by +#acquire_lock+
+      def release_lock: (Storage::RecoveryLockToken) -> void
+    end
+  end
+end

data/sig/_private/stoplight/domain/ports/recovery_lock_token.rbs

@@ -0,0 +1,6 @@
+module Stoplight
+  module Domain
+    interface _RecoveryLockToken
+    end
+  end
+end

data/sig/_private/stoplight/domain/ports/run_strategy.rbs

@@ -0,0 +1,14 @@
+module Stoplight
+  module Domain
+    # Represents an abstract strategy for running a light's operations.
+    # Every new strategy should implement this interface
+    #
+    interface _RunStrategy
+      # @param fallback A fallback proc to execute in case of an error.
+      def execute: [T] (
+        (^(StandardError?) -> T)? fallback,
+        state_snapshot: StateSnapshot
+      ) { () -> T } -> T
+    end
+  end
+end

data/sig/_private/stoplight/domain/ports/state_store.rbs

@@ -0,0 +1,79 @@
+module Stoplight
+  module Domain
+    # 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
+    #
+    interface _StateStore
+      # 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.
+      #
+      def state_snapshot: () -> StateSnapshot
+
+      # 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 The new state to set.
+      # @return The state that was set.
+      def set_state: (state) -> state
+
+      # 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 The target color/state to transition to.
+      #   Should be one of Stoplight::Color::GREEN, Stoplight::Color::YELLOW, or Stoplight::Color::RED.
+      #
+      # @return 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) -> bool
+
+      # 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.
+      #
+      def clear: () -> void
+    end
+  end
+end

data/sig/_private/stoplight/domain/ports/traffic_control.rbs

@@ -0,0 +1,41 @@
+module Stoplight
+  module Domain
+    # 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
+    #     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
+    #
+    interface _TrafficControl
+      # Checks if the strategy is compatible with the given Stoplight configuration.
+      def check_compatibility: (Config) -> CompatibilityResult
+
+      # Determines whether traffic should be stopped based on the Stoplight's
+      # current state and metrics.
+      # @return +true+ if traffic should be stopped otherwise false
+      def stop_traffic?: (Config, Domain::MetricsSnapshot) -> bool
+
+      # Object methods
+      def ==: (untyped) -> bool
+      def is_a?: (untyped) -> bool
+    end
+  end
+end

data/sig/_private/stoplight/domain/ports/traffic_recovery.rbs

@@ -0,0 +1,47 @@
+module Stoplight
+  module Domain
+    type decision = :green | :yellow | :red
+
+    # 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
+    #     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
+    #
+    interface _TrafficRecovery
+      # Checks if the strategy is compatible with the given Stoplight configuration.
+      def check_compatibility: (Config) -> CompatibilityResult
+
+      # Determines the appropriate recovery state based on the Stoplight's
+      # current metrics and recovery progress.
+      def determine_color: (Config, Domain::MetricsSnapshot) -> decision
+
+      # Object methods
+      def ==: (untyped) -> bool
+      def is_a?: (untyped) -> bool
+    end
+  end
+end

data/sig/_private/stoplight/domain/state_snapshot.rbs

@@ -0,0 +1,32 @@
+module Stoplight
+  module Domain
+    class StateSnapshot < Data
+      def breached_at: -> Time?
+      def locked_state: -> state
+      def recovery_scheduled_after: -> Time?
+      def recovery_scheduled_after!: -> Time
+      def recovery_started_at: -> Time?
+      def recovery_started_at!: -> Time
+      def time: -> Time
+
+      def self.new: (
+          breached_at: Time?,
+          locked_state: state,
+          recovery_scheduled_after: Time?,
+          recovery_started_at: Time?,
+          time: Time
+        ) -> instance
+
+      def initialize: (
+        breached_at: Time?,
+        locked_state: state,
+        recovery_scheduled_after: Time?,
+        recovery_started_at: Time?,
+        time: Time
+        ) -> void
+
+      def color: -> color
+      def recovery_started?: -> bool
+    end
+  end
+end

data/sig/_private/stoplight/domain/storage/recovery_lock_token.rbs

@@ -0,0 +1,11 @@
+module Stoplight
+  module Domain
+    module Storage
+      class RecoveryLockToken
+        include _RecoveryLockToken
+
+        attr_reader token: String
+      end
+    end
+  end
+end

data/sig/_private/stoplight/domain/strategies/green_run_strategy.rbs

@@ -0,0 +1,17 @@
+module Stoplight
+  module Domain
+    module Strategies
+      class GreenRunStrategy
+        include _RunStrategy
+
+        attr_reader request_tracker: Tracker::Request
+        @error_tracking_policy: ErrorTrackingPolicy
+
+        def initialize: (error_tracking_policy: ErrorTrackingPolicy, request_tracker: Tracker::Request) -> void
+
+        def record_error: (StandardError) -> void
+        def record_success: -> void
+      end
+    end
+  end
+end

data/sig/_private/stoplight/domain/strategies/red_run_strategy.rbs

@@ -0,0 +1,17 @@
+module Stoplight
+  module Domain
+    module Strategies
+      class RedRunStrategy
+        include _RunStrategy
+
+        @name: String
+        @cool_off_time: duration
+
+        def initialize: (name: String, cool_off_time: duration) -> void
+
+        private def record_error: (StandardError) -> void
+        private def record_success: -> void
+      end
+    end
+  end
+end

data/sig/_private/stoplight/domain/strategies/yellow_run_strategy.rbs

@@ -0,0 +1,42 @@
+module Stoplight
+  module Domain
+    module Strategies
+      class YellowRunStrategy
+        include _RunStrategy
+
+        attr_reader state_store: Domain::_StateStore
+        attr_reader metrics_store: _MetricsStore
+        attr_reader recovery_lock_store: _RecoveryLockStore
+        attr_reader notifiers: Array[state_transition_notifier]
+        attr_reader request_tracker: Tracker::RecoveryProbe
+        attr_reader red_run_strategy: RedRunStrategy
+
+        @name: String
+        @config: Domain::Config
+        @error_tracking_policy: ErrorTrackingPolicy
+
+        def initialize: (
+          name: String,
+          error_tracking_policy: ErrorTrackingPolicy,
+          notifiers: Array[state_transition_notifier],
+          request_tracker: Tracker::RecoveryProbe,
+          red_run_strategy: RedRunStrategy,
+          state_store: Domain::_StateStore,
+          metrics_store: _MetricsStore,
+          recovery_lock_store: _RecoveryLockStore,
+          config: Domain::Config,
+        ) -> void
+
+        def with_recovery_lock: [T] (
+            fallback: (^(StandardError?) -> T)?,
+            state_snapshot: StateSnapshot,
+            code: ^() -> T,
+          ) { () -> T } -> T
+
+        def record_recovery_probe_success: () -> void
+        def record_recovery_probe_failure: (StandardError) -> void
+        def enter_recovery: (StateSnapshot) -> void
+      end
+    end
+  end
+end

data/{lib/stoplight/domain/tracker/base.rb → sig/_private/stoplight/domain/tracker/base.rbs}

@@ -1,10 +1,6 @@
-# frozen_string_literal: true
-
 module Stoplight
   module Domain
     module Tracker
-      # @api private
-      # @abstract
       class Base
       end
     end

data/sig/_private/stoplight/domain/tracker/recovery_probe.rbs

@@ -0,0 +1,25 @@
+module Stoplight
+  module Domain
+    module Tracker
+      class RecoveryProbe < Base
+        attr_reader traffic_recovery: _TrafficRecovery
+        attr_reader notifiers: Array[state_transition_notifier]
+        attr_reader config: Config
+        attr_reader metrics_store: _MetricsStore
+        attr_reader state_store: _StateStore
+
+        def initialize: (
+          config: Config,
+          traffic_recovery: _TrafficRecovery,
+          notifiers: Array[state_transition_notifier],
+          metrics_store: _MetricsStore,
+          state_store: _StateStore,
+        ) -> void
+
+        def record_failure: (StandardError exception) -> void
+        def record_success: -> void
+        def recover: -> void
+      end
+    end
+  end
+end

data/sig/_private/stoplight/domain/tracker/request.rbs

@@ -0,0 +1,26 @@
+module Stoplight
+  module Domain
+    module Tracker
+      class Request < Base
+        attr_reader config: Config
+        attr_reader traffic_control: _TrafficControl
+        attr_reader notifiers: Array[state_transition_notifier]
+        attr_reader metrics_store: _MetricsStore
+        attr_reader state_store: _StateStore
+
+        def initialize: (
+          config: Config,
+          traffic_control: _TrafficControl,
+          notifiers: Array[state_transition_notifier],
+          metrics_store: _MetricsStore,
+          state_store: _StateStore,
+        ) -> void
+
+        def record_failure: (StandardError exception) -> void
+        def record_success: -> void
+
+        private def transition_to_red: (StandardError exception, metrics: MetricsSnapshot) -> void
+      end
+    end
+  end
+end

data/sig/_private/stoplight/domain/traffic_control/consecutive_errors.rbs

@@ -0,0 +1,9 @@
+module Stoplight
+  module Domain
+    module TrafficControl
+      class ConsecutiveErrors
+        include _TrafficControl
+      end
+    end
+  end
+end

data/sig/_private/stoplight/domain/traffic_control/error_rate.rbs

@@ -0,0 +1,13 @@
+module Stoplight
+  module Domain
+    module TrafficControl
+      class ErrorRate
+        include _TrafficControl
+
+        attr_reader min_requests: Integer
+
+        def initialize: (?min_requests: Integer) -> void
+      end
+    end
+  end
+end

data/sig/_private/stoplight/domain/traffic_recovery/consecutive_successes.rbs

@@ -0,0 +1,9 @@
+module Stoplight
+  module Domain
+    module TrafficRecovery
+      class ConsecutiveSuccesses
+        include _TrafficRecovery
+      end
+    end
+  end
+end

data/sig/_private/stoplight/domain/traffic_recovery.rbs

@@ -0,0 +1,9 @@
+module Stoplight
+  module Domain
+    module TrafficRecovery
+      GREEN: :green
+      YELLOW: :yellow
+      RED: :red
+    end
+  end
+end

data/sig/_private/stoplight/infrastructure/fail_safe/data_store.rbs

@@ -0,0 +1,26 @@
+module Stoplight
+  module Infrastructure
+    module FailSafe
+      class DataStore
+        include Domain::_DataStore
+        attr_reader data_store: Domain::_DataStore
+        attr_reader failover_data_store: Domain::_DataStore
+        attr_reader error_notifier: error_notifier
+        private attr_reader circuit_breaker: Domain::Light
+
+        def initialize: (
+          data_store: Domain::_DataStore,
+          error_notifier: error_notifier,
+          failover_data_store: Domain::_DataStore,
+          circuit_breaker: Domain::Light
+        ) -> void
+
+        private def with_fallback: [T] (
+          String | Symbol method_name,
+          *untyped,
+          **untyped,
+        ) { () -> T } -> T
+      end
+    end
+  end
+end

data/sig/_private/stoplight/infrastructure/fail_safe/storage/metrics.rbs

@@ -0,0 +1,25 @@
+module Stoplight
+  module Infrastructure
+    module FailSafe
+      module Storage
+        class Metrics
+          include Domain::_MetricsStore
+
+          attr_reader primary_store: Domain::_MetricsStore
+          attr_reader error_notifier: error_notifier
+          attr_reader failover_store: Domain::_MetricsStore
+          attr_reader circuit_breaker: Domain::Light
+
+          def initialize: (
+            primary_store: Domain::_MetricsStore,
+            error_notifier: error_notifier,
+            failover_store: Domain::_MetricsStore,
+            circuit_breaker: Domain::Light
+          ) -> void
+
+          def fallback: [T] { () -> T } -> ^(StandardError?) -> T
+        end
+      end
+    end
+  end
+end