stoplight 5.8.3 → 6.0.0.rc2

data/sig/stoplight/admin.rbs

@@ -0,0 +1,14 @@
+module Stoplight
+  class Admin < Sinatra::Base
+    COLORS: Array[Domain::color]
+    ASSETS_PATH: String
+    ASSET_DIGESTS: Hash[String, String]
+    ONE_YEAR_IN_SECONDS: Integer
+    include Helpers
+
+    self.@systems: Array[Wiring::System]
+    def self.add_system: (Wiring::System) -> void
+    def self.__stoplight__reset_systems!: -> void
+    def self.validate_persistent_system!: (Wiring::System) -> Wiring::System
+  end
+end

data/sig/stoplight/color.rbs

@@ -1,7 +1,7 @@
 module Stoplight
   module Color
-    GREEN: green
-    YELLOW: yellow
-    RED: red
+    GREEN: Domain::green
+    YELLOW: Domain::yellow
+    RED: Domain::red
   end
 end

data/sig/{_private/stoplight/data_store.rbs → stoplight/data_store/base.rbs}

@@ -1,5 +1,6 @@
 module Stoplight
   module DataStore
+    # @api private
     class Base
     end
   end

data/sig/stoplight/data_store/memory.rbs

@@ -0,0 +1,9 @@
+module Stoplight
+  module DataStore
+    # Configuration for Memory-backed Stoplight storage.
+    #
+    # @note This is a configuration object, not the storage implementation itself.
+    class Memory < Base
+    end
+  end
+end

data/sig/stoplight/data_store/redis.rbs

@@ -0,0 +1,17 @@
+module Stoplight
+  module DataStore
+    # Configuration for Redis-backed Stoplight storage.
+    #
+    # @note This is a configuration object, not the storage implementation itself.
+    class Redis < Base
+      KEY_SPACE: Infrastructure::Redis::Key
+
+      attr_reader redis: Infrastructure::redis
+
+      def initialize: (Infrastructure::redis) -> void
+
+      def self.key_space: -> Infrastructure::Redis::Key
+      def key_space: -> Infrastructure::Redis::Key
+    end
+  end
+end

data/sig/{_private/stoplight → stoplight}/domain/config.rbs

@@ -1,64 +1,68 @@
 module Stoplight
   module Domain
     class Config < Data
+      attr_reader id: String
       attr_reader threshold: percentage | Integer
-      attr_reader window_size: duration?
-      attr_reader tracked_errors: Array[_ExceptionMatcher]
-      attr_reader skipped_errors: Array[_ExceptionMatcher]
+      attr_reader window_size: duration_seconds?
+      attr_reader tracked_errors: Array[Module]
+      attr_reader skipped_errors: Array[Module]
       attr_reader name: String
-      attr_reader cool_off_time: duration
+      attr_reader cool_off_time: duration_seconds
       attr_reader recovery_threshold: Integer
       attr_reader traffic_control: _TrafficControl
       attr_reader traffic_recovery: _TrafficRecovery
       attr_reader error_notifier: error_notifier
-      attr_reader notifiers: Array[state_transition_notifier]
-      attr_reader data_store: data_store
+      attr_reader notifiers: Array[_StateTransitionNotifier]
+      attr_reader data_store: _DataStore
 
       def self.new: (
+          id: String,
           name: String,
-          cool_off_time: duration,
+          cool_off_time: duration_seconds,
           threshold: percentage | Integer,
           recovery_threshold: Integer,
-          window_size: duration?,
-          tracked_errors: Array[_ExceptionMatcher],
-          skipped_errors: Array[_ExceptionMatcher],
+          window_size: duration_seconds?,
+          tracked_errors: Array[Module],
+          skipped_errors: Array[Module],
           traffic_control: _TrafficControl,
           traffic_recovery: _TrafficRecovery,
           error_notifier: error_notifier,
-          notifiers: Array[state_transition_notifier],
-          data_store: data_store
+          notifiers: Array[_StateTransitionNotifier],
+          data_store: _DataStore
         ) -> instance
 
       def initialize: (
+          id:  String,
           name: String,
-          cool_off_time: duration,
+          cool_off_time: duration_seconds,
           threshold: percentage | Integer,
           recovery_threshold: Integer,
-          window_size: duration?,
-          tracked_errors: Array[_ExceptionMatcher],
-          skipped_errors: Array[_ExceptionMatcher],
+          window_size: duration_seconds?,
+          tracked_errors: Array[Module],
+          skipped_errors: Array[Module],
           traffic_control: _TrafficControl,
           traffic_recovery: _TrafficRecovery,
           error_notifier: error_notifier,
-          notifiers: Array[state_transition_notifier],
-          data_store: data_store
+          notifiers: Array[_StateTransitionNotifier],
+          data_store: _DataStore
         ) -> void
 
       def cool_off_time_in_milliseconds: () -> Integer
 
       def with: (
+          ?id: optional[String],
           ?name: optional[String],
-          ?cool_off_time: optional[duration],
+          ?cool_off_time: optional[duration_seconds],
           ?threshold: optional[percentage | Integer],
           ?recovery_threshold: optional[Integer],
-          ?window_size: optional[duration?],
-          ?tracked_errors: optional[Array[_ExceptionMatcher]],
-          ?skipped_errors: optional[Array[_ExceptionMatcher]],
+          ?window_size: optional[duration_seconds?],
+          ?tracked_errors: optional[Array[Module]],
+          ?skipped_errors: optional[Array[Module]],
           ?traffic_control: optional[_TrafficControl],
           ?traffic_recovery: optional[_TrafficRecovery],
           ?error_notifier: optional[error_notifier],
-          ?notifiers: optional[Array[state_transition_notifier]],
-          ?data_store: optional[data_store],
+          ?notifiers: optional[Array[_StateTransitionNotifier]],
+          ?data_store: optional[_DataStore],
       ) -> Config | () -> Config
     end
   end

data/sig/{_private/stoplight → stoplight}/domain/error_tracking_policy.rbs

@@ -5,6 +5,10 @@ module Stoplight
       @skipped: Array[_ExceptionMatcher]
 
       def initialize: (tracked: Array[_ExceptionMatcher], skipped: Array[_ExceptionMatcher]) -> void
+      def with: (
+        ?tracked: optional[Array[_ExceptionMatcher] | _ExceptionMatcher],
+        ?skipped: optional[Array[_ExceptionMatcher] | _ExceptionMatcher]
+      ) -> ErrorTrackingPolicy
       def track?: (StandardError) -> bool
 
       def skipped?: (StandardError) -> bool

data/sig/{_private/stoplight → stoplight}/domain/failure.rbs

@@ -11,6 +11,8 @@ module Stoplight
       def initialize: (String error_class, String error_message, Time time) -> void
 
       def ==: (untyped other) -> bool
+      def eql?: (untyped other) -> bool
+      def hash: () -> Integer
     end
   end
 end

data/sig/stoplight/domain/id.rbs

@@ -0,0 +1,7 @@
+module Stoplight
+  module Domain
+    module Id
+      def self.for: (String) -> String
+    end
+  end
+end

data/sig/stoplight/domain/light.rbs

@@ -0,0 +1,39 @@
+module Stoplight
+  module Domain
+    class Light
+      attr_reader name: String
+      attr_reader green_run_strategy: Strategies::GreenRunStrategy
+      attr_reader yellow_run_strategy: Strategies::YellowRunStrategy
+      attr_reader red_run_strategy: Strategies::RedRunStrategy
+      attr_reader state_store: _StateStore
+
+      @name: String
+      @lock_control: LockControl
+      @error_tracking_policy: ErrorTrackingPolicy
+
+      def initialize: (
+        String name,
+        green_run_strategy: Strategies::GreenRunStrategy,
+        yellow_run_strategy: Strategies::YellowRunStrategy,
+        red_run_strategy: Strategies::RedRunStrategy,
+        state_store: _StateStore,
+        lock_control: LockControl,
+        error_tracking_policy: ErrorTrackingPolicy
+      ) -> void
+
+      def state: -> Domain::state
+      def color: -> Domain::color
+      def run: [T] (
+          ?(^(StandardError?) -> T)?,
+          ?tracked_errors: optional[Array[Domain::_ExceptionMatcher] | Domain::_ExceptionMatcher],
+          ?skipped_errors: optional[Array[Domain::_ExceptionMatcher] | Domain::_ExceptionMatcher]
+        ) { () -> T } -> T
+      def lock: (Domain::color) -> Light
+      def unlock: -> Light
+
+      private
+      def state_strategy_factory: (color) -> _RunStrategy
+      def state_snapshot: -> StateSnapshot
+    end
+  end
+end

data/sig/{_private/stoplight → stoplight}/domain/light_info.rbs

@@ -1,7 +1,7 @@
 module Stoplight
   module Domain
     class LightInfo < Data
-      include _LightInfo
+      attr_reader name: String
 
       def self.new: (
           name: String,
@@ -10,10 +10,6 @@ module Stoplight
       def initialize: (
           name: String,
         ) -> void
-
-      def with: (
-          ?name: String,
-      ) -> LightInfo
     end
   end
 end

data/sig/stoplight/domain/lock_control.rbs

@@ -0,0 +1,16 @@
+module Stoplight
+  module Domain
+    class LockControl
+      @state_store: _StateStore
+      @emitter: Telemetry::Emitter
+
+      def initialize: (
+          state_store: _StateStore,
+          emitter: Telemetry::Emitter
+        ) -> void
+
+      def lock: (color) -> void
+      def unlock: -> void
+    end
+  end
+end

data/sig/stoplight/domain/matcher_validator.rbs

@@ -0,0 +1,11 @@
+module Stoplight
+  module Domain
+    class MatcherValidator
+      def self.call: (Module) -> String
+
+      private
+
+      def self.message: (Module) -> String
+    end
+  end
+end

data/sig/{_private/stoplight → stoplight}/domain/ports/clock.rbs

@@ -11,6 +11,12 @@ module Stoplight
       # Returns the current time.
       def current_time: () -> Time
 
+      # Returns monotonic time in ms
+      def monotonic_millis: () -> Float
+
+      # Returns monotonic time in s
+      def monotonic_seconds: () -> Float
+
       # Converts a Unix timestamp to a Time object.
       def at: (timestamp) -> Time
     end

data/sig/stoplight/domain/ports/data_store.rbs

@@ -0,0 +1,9 @@
+module Stoplight
+  module Domain
+    # Data store configuration, specifies which data store should be
+    # used to store Stoplight state
+    interface _DataStore
+      def is_a?: (untyped klass) -> bool
+    end
+  end
+end

data/sig/stoplight/domain/ports/error_notifier.rbs

@@ -0,0 +1,12 @@
+module Stoplight
+  module Domain
+    # Called when Stoplight internals fail (e.g. Redis unavailable, notifier I/O).
+    interface _ErrorNotifier
+      def call: (StandardError) -> void
+
+      # Object methods
+      def ==: (untyped) -> bool
+      def is_a?: (untyped) -> bool
+    end
+  end
+end

data/sig/stoplight/domain/ports/exception_matcher.rbs

@@ -0,0 +1,10 @@
+module Stoplight
+  module Domain
+    interface _ExceptionMatcher
+      def ===: (untyped) -> bool
+
+      # Object methods
+      def is_a?: (untyped) -> bool
+    end
+  end
+end

data/sig/{_private/stoplight → stoplight}/domain/ports/metrics_store.rbs

@@ -19,8 +19,8 @@ module Stoplight
       # Records a successful circuit breaker execution
       def record_success: () -> void
 
-      # Records a failed circuit breaker execution
-      def record_failure: (StandardError error) -> void
+      # Records a failed circuit breaker execution and returns the resulting snapshot
+      def record_failure: (StandardError error) -> Domain::MetricsSnapshot
 
       # Clears all metrics for this circuit
       def clear: () -> void

data/sig/stoplight/domain/ports/registry.rbs

@@ -0,0 +1,13 @@
+module Stoplight
+  module Domain
+    # Holds the information about existing lights.
+    # Each system has its own registry so you can query lights belonging to it.
+    interface _Registry
+      def ids: -> Array[String]
+      def register: (Config) -> void
+      def unregister: (String id) -> void
+      def config_for: (String id) -> Hash[String, untyped]?
+      def all_configs: -> Array[Hash[String, untyped]]
+    end
+  end
+end

data/sig/{_private/stoplight → stoplight}/domain/ports/run_strategy.rbs

@@ -7,7 +7,8 @@ module Stoplight
       # @param fallback A fallback proc to execute in case of an error.
       def execute: [T] (
         (^(StandardError?) -> T)? fallback,
-        state_snapshot: StateSnapshot
+        state_snapshot: StateSnapshot,
+        error_tracking_policy: ErrorTrackingPolicy
       ) { () -> T } -> T
     end
   end

data/sig/stoplight/domain/ports/state_transition_notifier.rbs

@@ -0,0 +1,18 @@
+module Stoplight
+  module Domain
+    interface _StateTransitionNotifier
+      # Sends a notification when a Stoplight changes state.
+      #
+      # @param light The Stoplight instance triggering the notification.
+      # @param from_color The previous state color of the Stoplight.
+      # @param to_color The new state color of the Stoplight.
+      # @param error The error (if any) that caused the state change.
+      def notify: (Domain::LightInfo, Domain::color from_color, Domain::color to_color, ?StandardError? error) -> void
+
+      # Object methods needed for comparison/inspection
+      def ==: (untyped) -> bool
+
+      def class: -> Class
+    end
+  end
+end

data/sig/stoplight/domain/ports/telemetry.rbs

@@ -0,0 +1,28 @@
+module Stoplight
+  module Domain
+    # Consumer-facing side of the telemetry bus: subscription only. The producer side is internal
+    # (see Domain::_TelemetryPublisher). This is what +_System#telemetry+ returns.
+    interface _Telemetry
+      # Supports the following variants:
+      #  - Firehose (no filter): every event, including types added in future versions - filter by payload class
+      #    (+case envelope.payload+ narrows the union).
+      #  - Filtered by event class: only that event, with the envelope's payload pre-narrowed.
+      #  - Filtered by +StateTransitioned+: the closed transition union - the complete color timeline.
+      #
+      # @raise [Stoplight::Error::TooManySubscriptions] if the bus's subscription cap is reached.
+      def subscribe: () { (Telemetry::Envelope[Telemetry::event]) -> void } -> Telemetry::Subscription
+        | (singleton(Telemetry::RunCompleted)) { (Telemetry::Envelope[Telemetry::RunCompleted]) -> void } -> Telemetry::Subscription
+        | (singleton(Telemetry::TrafficBreached)) { (Telemetry::Envelope[Telemetry::TrafficBreached]) -> void } -> Telemetry::Subscription
+        | (singleton(Telemetry::RecoveryStarted)) { (Telemetry::Envelope[Telemetry::RecoveryStarted]) -> void } -> Telemetry::Subscription
+        | (singleton(Telemetry::RecoverySucceeded)) { (Telemetry::Envelope[Telemetry::RecoverySucceeded]) -> void } -> Telemetry::Subscription
+        | (singleton(Telemetry::RecoveryFailed)) { (Telemetry::Envelope[Telemetry::RecoveryFailed]) -> void } -> Telemetry::Subscription
+        | (singleton(Telemetry::LockChanged)) { (Telemetry::Envelope[Telemetry::LockChanged]) -> void } -> Telemetry::Subscription
+        | (singleton(Telemetry::RecoveryProbeCompleted)) { (Telemetry::Envelope[Telemetry::RecoveryProbeCompleted]) -> void } -> Telemetry::Subscription
+        | (singleton(Telemetry::LightRegistered)) { (Telemetry::Envelope[Telemetry::LightRegistered]) -> void } -> Telemetry::Subscription
+        | (singleton(Telemetry::StateTransitioned)) { (Telemetry::Envelope[Telemetry::state_transitioned]) -> void } -> Telemetry::Subscription
+
+      # Idempotent: removing an already-removed or unknown token is a no-op.
+      def unsubscribe: (Telemetry::Subscription) -> void
+    end
+  end
+end

data/sig/stoplight/domain/ports/telemetry_publisher.rbs

@@ -0,0 +1,14 @@
+module Stoplight
+  module Domain
+    # Producer-facing side of the telemetry bus, injected into Telemetry::Emitter. End users never
+    # see it: they get the consumer side (_Telemetry) from +_System#telemetry+.
+    interface _TelemetryPublisher
+      # True when any subscriber (firehose, exact class, or via the StateTransitioned marker) would
+      # receive this event class. The Emitter guards on it before building anything.
+      def subscribed?: (Telemetry::event_class) -> bool
+
+      # Delivers to every interested subscriber, synchronously, in subscription order.
+      def publish: (Telemetry::Envelope[Telemetry::event]) -> void
+    end
+  end
+end

data/sig/{_private/stoplight → stoplight}/domain/ports/traffic_control.rbs

@@ -22,6 +22,10 @@ module Stoplight
     #       error_rate = metrics.failures.fdiv(total)
     #       error_rate >= 0.5 # Stop traffic when error rate reaches 50%
     #     end
+    #
+    #     def name
+    #       "error_rate_custom"
+    #     end
     #   end
     #
     interface _TrafficControl
@@ -33,6 +37,9 @@ module Stoplight
       # @return +true+ if traffic should be stopped otherwise false
       def stop_traffic?: (Config, Domain::MetricsSnapshot) -> bool
 
+      # Returns a string identifier for this policy (e.g. "consecutive_errors", "error_rate").
+      def name: () -> String
+
       # Object methods
       def ==: (untyped) -> bool
       def is_a?: (untyped) -> bool

data/sig/{_private/stoplight → stoplight}/domain/ports/traffic_recovery.rbs

@@ -1,7 +1,5 @@
 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.
@@ -37,11 +35,12 @@ module Stoplight
 
       # Determines the appropriate recovery state based on the Stoplight's
       # current metrics and recovery progress.
-      def determine_color: (Config, Domain::MetricsSnapshot) -> decision
+      def determine_color: (Config, Domain::MetricsSnapshot) -> recovery_decision
 
       # Object methods
       def ==: (untyped) -> bool
       def is_a?: (untyped) -> bool
+      def name: -> String
     end
   end
 end

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

@@ -0,0 +1,22 @@
+module Stoplight
+  module Domain
+    module Strategies
+      class GreenRunStrategy
+        include _RunStrategy
+
+        attr_reader request_tracker: Tracker::Request
+        @run_recorder: Telemetry::RunRecorder
+        @clock: _Clock
+
+        def initialize: (request_tracker: Tracker::Request,
+            run_recorder: Telemetry::RunRecorder, clock: _Clock) -> void
+
+        def capture_started_at: () -> Float?
+        def duration_since: (Float?) -> duration_ms?
+
+        def record_error: (StandardError, duration_ms: duration_ms?, fallback_used: bool) -> void
+        def record_success: (duration_ms: duration_ms?, ?error: StandardError?)-> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Stoplight
+  module Domain
+    module Strategies
+      class RedRunStrategy
+        include _RunStrategy
+
+        @name: String
+        @cool_off_time: duration_seconds
+        @run_recorder: Telemetry::RunRecorder
+
+        def initialize: (
+            name: String,
+            cool_off_time: duration_seconds,
+            run_recorder: Telemetry::RunRecorder,
+          ) -> void
+      end
+    end
+  end
+end

data/sig/{_private/stoplight → stoplight}/domain/strategies/yellow_run_strategy.rbs

@@ -7,34 +7,45 @@ module Stoplight
         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
+        @clock: _Clock
+        @run_recorder: Telemetry::RunRecorder
+        @emitter: Telemetry::Emitter
 
         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,
+          state_store: _StateStore,
           metrics_store: _MetricsStore,
           recovery_lock_store: _RecoveryLockStore,
-          config: Domain::Config,
+          config: Config,
+          clock: _Clock,
+          run_recorder: Telemetry::RunRecorder,
+          emitter: Telemetry::Emitter
         ) -> void
 
         def with_recovery_lock: [T] (
             fallback: (^(StandardError?) -> T)?,
             state_snapshot: StateSnapshot,
-            code: ^() -> T,
-          ) { () -> T } -> T
+          ) { (duration_ms) -> T } -> T
+
+        def capture_started_at: () -> Float
+        def duration_since: (duration_ms) -> duration_ms
+
+        def record_recovery_probe_success: (
+            duration_ms: duration_ms,
+            ?error: StandardError?
+          ) -> void
+
+        def record_recovery_probe_failure: (
+            StandardError,
+            duration_ms: duration_ms,
+            fallback_used: bool,
+          ) -> void
 
-        def record_recovery_probe_success: () -> void
-        def record_recovery_probe_failure: (StandardError) -> void
         def enter_recovery: (StateSnapshot) -> void
       end
     end

data/sig/stoplight/domain/telemetry/bus.rbs

@@ -0,0 +1,49 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # In-process telemetry bus.
+      #
+      # Contract:
+      # - Events are process-local observations: they describe what this process observed or did, not the
+      #   globally shared circuit state.
+      # - Every color change this process observes or effects emits exactly one +state_transitioned+ event. That
+      #   stream alone reconstructs the color timeline (breaches, recovery, and locks included).
+      # - Events are traffic-driven - no traffic, no events.
+      # - Handlers run synchronously on the calling thread and are error-isolated:
+      #   a raising handler is routed to the error notifier and never affects the run.
+      # - Emission allocates nothing when nothing is subscribed to that event class - a transitions-only
+      #   subscriber keeps RunCompleted emission free.
+      # - Publish pays for interested handlers only: no filter matching happens at publish time
+      #   (interest is resolved at subscribe time), and subscriptions to other event classes add
+      #   nothing. The handlers themselves run inline, so their cost belongs to the subscriber.
+      #   Subscribing mid-publish takes effect on the next publish.
+      class Bus
+        # The consumer side (subscribe/unsubscribe), what +_System#telemetry+ returns.
+        include _Telemetry
+
+        # The producer side (publish/subscribed?), what wiring injects into Emitter.
+        include _TelemetryPublisher
+
+        @error_notifier: error_notifier
+        @mutex: Mutex
+        @max_subscriptions: Integer
+        @subscriptions: Array[[Subscription, subscription_filter, subscription_handler]]
+        @dispatch: Hash[Class, Array[subscription_handler]]
+
+        # Default cap on live subscriptions.
+        MAX_SUBSCRIPTIONS: Integer
+
+        # @param error_notifier receives any StandardError a subscriber's handler raises.
+        # @param max_subscriptions caps the number of live subscriptions - #subscribe raises
+        #   Stoplight::Error::TooManySubscriptions once reached.
+        def initialize: (error_notifier: error_notifier, ?max_subscriptions: Integer) -> void
+
+        # Value-level mirror of the +event+ union. A new event type is added here and to the union
+        # together (a spec pins them in sync).
+        EVENT_CLASSES: Array[event_class]
+
+        private def rebuild: -> void
+      end
+    end
+  end
+end

data/sig/stoplight/domain/telemetry/consumer.rbs

@@ -0,0 +1,13 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      class Consumer
+        include _Telemetry
+
+        @telemetry: untyped
+
+        def initialize: (_Telemetry) -> void
+      end
+    end
+  end
+end