stoplight 5.8.3 → 6.0.0.rc2

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

@@ -0,0 +1,51 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # The producer side of the bus. One per light, bound to its coordinates at construction time in
+      # wiring, responsible for building envelopes. Injected into strategies, trackers, and Light the same
+      # way notifiers are today.
+      class Emitter
+        @bus: _TelemetryPublisher
+        @clock: _Clock
+        @system_name: String
+        @light_name: String
+        @error_notifier: error_notifier
+
+        def initialize: (
+            bus: _TelemetryPublisher,
+            clock: _Clock,
+            system_name: String,
+            light_name: String,
+            error_notifier: error_notifier
+          ) -> void
+
+        # True when any subscriber would receive this event class.
+        def subscribed?: (Telemetry::event_class) -> bool
+
+        # Lazily yields the event's payload only when the bus has subscribers for this event class, then stamps
+        # +occurred_at+ from the clock and publishes.
+        #
+        # Emitting an unwatched event class allocates nothing - no payload, no envelope.
+        #
+        # The leading class argument is what lets the per-class guard run before the payload exists. Each overload
+        # pins the block's return type to it, so a mismatch is a Steep error at the emission site.
+        #
+        # @example
+        #   emitter.emit(Telemetry::RecoveryStarted) do
+        #     RecoveryStarted.new(from_color: "red", to_color: "yellow", breached_at: Time.now)
+        #   end
+        #
+        def emit: (singleton(RunCompleted)) { () -> RunCompleted } -> void
+                | (singleton(TrafficBreached)) { () -> TrafficBreached } -> void
+                | (singleton(RecoveryStarted)) { () -> RecoveryStarted } -> void
+                | (singleton(RecoverySucceeded)) { () -> RecoverySucceeded } -> void
+                | (singleton(RecoveryFailed)) { () -> RecoveryFailed } -> void
+                | (singleton(LockChanged)) { () -> LockChanged } -> void
+                | (singleton(RecoveryProbeCompleted)) { () -> RecoveryProbeCompleted } -> void
+                | (singleton(LightRegistered)) { () -> LightRegistered } -> void
+
+        private def notify_error: (StandardError) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # Wraps every published event. Carries only what the emission site knows.
+      #
+      # Identity, sequencing, and transport-level enrichment (ids, host, app version, deploy), etc. belong to the
+      # exporter, which can attach them at delivery time.
+      class Envelope[out P < event] < Data
+        attr_reader system_name: String
+        attr_reader light_name: String
+        attr_reader occurred_at: Time
+        attr_reader payload: P
+
+        def self.new: [Q < event] (
+            system_name: String,
+            light_name: String,
+            occurred_at: Time,
+            payload: Q
+          ) -> Envelope[Q]
+
+        def initialize: (
+            system_name: String,
+            light_name: String,
+            occurred_at: Time,
+            payload: P
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # Carries the live exception.
+      class Failure < Data
+        attr_reader exception: StandardError
+        # false when the exception matched skipped_errors: the light counted the run a success, but the caller still
+        # saw the exception.
+        attr_reader tracked: bool
+
+        def self.new: (
+            exception: StandardError,
+            tracked: bool
+          ) -> instance
+
+        def initialize: (
+            exception: StandardError,
+            tracked: bool
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # Emitted once per (process instance, system, light): the cache-miss branch of System#light.
+      #
+      # Consumers deduplicate by (system_name, light_name) + settings content.
+      #
+      # Emitted by wiring through the light's own emitter, after the light is fully constructed and before it is
+      # returned to the caller - so on the bus it precedes every other event of that light.
+      class LightRegistered < Data
+        attr_reader settings: Settings
+
+        def self.new: (
+            settings: Settings
+          ) -> instance
+
+        def initialize: (
+            settings: Settings
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # state_transitioned variant: manual lock override changed.
+      #
+      # Emitted even when the effective color is unchanged (from_color == to_color), so the lock timeline is complete.
+      class LockChanged < Data
+        include StateTransitioned
+
+        attr_reader from_color: color
+        attr_reader to_color: color
+        attr_reader from_state: state
+        attr_reader to_state: state
+
+        def self.new: (
+            from_color: color,
+            to_color: color,
+            from_state: state,
+            to_state: state,
+          ) -> instance
+
+        def initialize: (
+            from_color: color,
+            to_color: color,
+            from_state: state,
+            to_state: state,
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # The serializable subset of MetricsSnapshot. successes/errors are nil for non-windowed metrics.
+      class Metrics < Data
+        attr_reader successes: Integer?
+        attr_reader errors: Integer?
+        attr_reader consecutive_errors: Integer
+        attr_reader consecutive_successes: Integer
+
+        def self.new: (
+            successes: Integer?,
+            errors: Integer?,
+            consecutive_errors: Integer,
+            consecutive_successes: Integer
+          ) -> instance
+
+        def initialize: (
+            successes: Integer?,
+            errors: Integer?,
+            consecutive_errors: Integer,
+            consecutive_successes: Integer
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # state_transitioned variant: recovery policy sent the light back to red.
+      class RecoveryFailed < Data
+        include StateTransitioned
+
+        attr_reader from_color: yellow
+        attr_reader to_color: red
+        # Open set - the traffic-recovery policy self-identifies.
+        attr_reader policy: String
+        # Semantic nil: today's ConsecutiveSuccesses always has a triggering exception, but a future policy may fail
+        # a recovery without one (e.g. a deadline-based strategy).
+        attr_reader failure: Failure?
+        # Recovery metrics at the decision point.
+        attr_reader metrics: Metrics
+
+        def self.new: (
+            from_color: yellow,
+            to_color: red,
+            policy: String,
+            failure: Failure?,
+            metrics: Metrics
+          ) -> instance
+
+        def initialize: (
+            from_color: yellow,
+            to_color: red,
+            policy: String,
+            failure: Failure?,
+            metrics: Metrics
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # Emitted for every recovery probe.
+      class RecoveryProbeCompleted < Data
+        attr_reader outcome: probe_outcome
+        # Latency of the recovering dependency.
+        attr_reader duration_ms: Float
+        attr_reader failure: Failure?
+        # Recovery metrics after this probe.
+        attr_reader progress: Metrics
+
+        def self.new: (
+            outcome: probe_outcome,
+            duration_ms: Float,
+            failure: Failure?,
+            progress: Metrics
+          ) -> instance
+
+        def initialize: (
+            outcome: probe_outcome,
+            duration_ms: Float,
+            failure: Failure?,
+            progress: Metrics
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # state_transitioned variant: cool-off elapsed and the first probe explicitly entered recovery.
+      class RecoveryStarted < Data
+        include StateTransitioned
+
+        attr_reader from_color: red
+        attr_reader to_color: yellow
+        attr_reader breached_at: Time
+
+        def self.new: (
+            from_color: red,
+            to_color: yellow,
+            breached_at: Time
+          ) -> instance
+
+        def initialize: (
+            from_color: red,
+            to_color: yellow,
+            breached_at: Time
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # state_transitioned variant: recovery policy resumed traffic.
+      class RecoverySucceeded < Data
+        include StateTransitioned
+
+        attr_reader from_color: yellow
+        attr_reader to_color: green
+        # Open set - the traffic-recovery policy self-identifies ("consecutive_successes", custom).
+        attr_reader policy: String
+        # Recovery metrics at the decision point.
+        attr_reader metrics: Metrics
+
+        def self.new: (
+            from_color: yellow,
+            to_color: green,
+            policy: String,
+            metrics: Metrics
+          ) -> instance
+
+        def initialize: (
+            from_color: yellow,
+            to_color: green,
+            policy: String,
+            metrics: Metrics
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # Emitted for every Light#run.
+      class RunCompleted < Data
+        attr_reader outcome: run_outcome
+        attr_reader color: color
+        # nil when blocked (no user code ran)
+        # @note For performance reasons, durations might not be measured if nobody was subscribed at the start
+        # of the run - e.g. due to a race condition between active light and new subscription.
+        attr_reader duration_ms: Float?
+        # Present on failures and on successes caused by untracked (skipped) errors (see Failure#tracked).
+        attr_reader failure: Failure?
+        attr_reader fallback_used: bool
+        # Set only when blocked, nil under locked-red (no recovery scheduled).
+        attr_reader retry_after: Time?
+
+        def self.new: (
+            outcome: run_outcome,
+            color: color,
+            duration_ms: Float?,
+            failure: Failure?,
+            fallback_used: bool,
+            retry_after: Time?
+          ) -> instance
+
+        def initialize: (
+            outcome: run_outcome,
+            color: color,
+            duration_ms: Float?,
+            failure: Failure?,
+            fallback_used: bool,
+            retry_after: Time?
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # Builds and emits RunCompleted events for one light color.
+      class RunRecorder
+        @emitter: Telemetry::Emitter
+        @color: color
+
+        def initialize: (emitter: Telemetry::Emitter, color: color) -> void
+
+        def subscribed?: () -> bool
+
+        def record_success: (duration_ms: duration_ms?, ?error: StandardError?) -> void
+        def record_failure: (StandardError, duration_ms: duration_ms?, fallback_used: bool) -> void
+        def record_blocked: (fallback_used: bool, retry_after: Time?) -> void
+
+        private def emit: (
+            outcome: run_outcome,
+            duration_ms: Float?,
+            failure: Failure?,
+            fallback_used: bool,
+            retry_after: Time?
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # The serializable subset of a light's configuration. No live objects (notifiers, data stores, procs) cross the
+      # telemetry boundary.
+      class Settings < Data
+        attr_reader cool_off_time: duration_seconds
+        attr_reader threshold: Float | Integer
+        attr_reader recovery_threshold: Integer
+        attr_reader window_size: duration_seconds?
+        # Constant names of the error matchers (matchers are named constants responding to #===).
+        attr_reader tracked_errors: Array[String]
+        attr_reader skipped_errors: Array[String]
+        attr_reader traffic_control: String
+        attr_reader traffic_control_params: Hash[String, untyped]
+        attr_reader traffic_recovery: String
+        attr_reader traffic_recovery_params: Hash[String, untyped]
+
+        def self.new: (
+            cool_off_time: duration_seconds,
+            threshold: Float | Integer,
+            recovery_threshold: Integer,
+            window_size: duration_seconds?,
+            tracked_errors: Array[String],
+            skipped_errors: Array[String],
+            traffic_control: String,
+            traffic_control_params: Hash[String, untyped],
+            traffic_recovery: String,
+            traffic_recovery_params: Hash[String, untyped]
+          ) -> instance
+
+        def initialize: (
+            cool_off_time: duration_seconds,
+            threshold: Float | Integer,
+            recovery_threshold: Integer,
+            window_size: duration_seconds?,
+            tracked_errors: Array[String],
+            skipped_errors: Array[String],
+            traffic_control: String,
+            traffic_control_params: Hash[String, untyped],
+            traffic_recovery: String,
+            traffic_recovery_params: Hash[String, untyped]
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # Runtime name for the +state_transitioned+ union: a marker module included by every transition variant.
+      # Carries no behavior - it exists so subscription filters can dispatch on the union with
+      # Module#=== (RBS unions have no runtime constant). The type alias keeps typing the payload, this module names it at runtime.
+      module StateTransitioned
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # Opaque, single-use token returned by +Telemetry#subscribe+ and accepted by +Telemetry#unsubscribe+. No public behavior.
+      class Subscription
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      # state_transitioned variant: traffic control tripped the light.
+      class TrafficBreached < Data
+        include StateTransitioned
+
+        attr_reader from_color: green
+        attr_reader to_color: red
+        # Open set - the traffic-control policy self-identifies ("consecutive_errors", "error_rate", custom).
+        attr_reader policy: String
+        # Today's policies are consulted only when recording a failure, so a triggering exception is
+        # always present - but a future policy may breach without one (e.g. slow-call rate).
+        attr_reader failure: Failure?
+        # Request metrics at the decision point.
+        attr_reader metrics: Metrics
+
+        def self.new: (
+            from_color: green,
+            to_color: red,
+            policy: String,
+            failure: Failure?,
+            metrics: Metrics
+          ) -> instance
+
+        def initialize: (
+            from_color: green,
+            to_color: red,
+            policy: String,
+            failure: Failure?,
+            metrics: Metrics
+          ) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+module Stoplight
+  module Domain
+    module Telemetry
+      type subscription_handler = ^(Envelope[event]) -> void
+      type subscription_filter =  nil | singleton(RunCompleted) | singleton(TrafficBreached) | singleton(RecoveryStarted)
+        | singleton(RecoverySucceeded) | singleton(RecoveryFailed) | singleton(LockChanged)
+        | singleton(RecoveryProbeCompleted) | singleton(LightRegistered) | singleton(StateTransitioned)
+
+      # Run outcomes reflect the light's accounting, not the caller's experience: an untracked (skipped) error
+      # emits +:success+ with +failure.tracked = false+.
+      type run_outcome = :success | :failure | :blocked
+      type probe_outcome = :success | :failure
+
+      # Closed union over the state machine's edges. New traffic/recovery policies never add variants. They
+      # self-identify via the open +policy+ string inside the matching variant. Every variant includes
+      # the +StateTransitioned+ marker module - the union's runtime name.
+      type state_transitioned = TrafficBreached | RecoveryStarted | RecoverySucceeded | RecoveryFailed | LockChanged
+
+      type event = RunCompleted | state_transitioned | RecoveryProbeCompleted | LightRegistered
+
+      # The +event+ union at the class level - what emit and subscribed? take.
+      type event_class = singleton(RunCompleted)
+        | singleton(TrafficBreached)
+        | singleton(RecoveryStarted)
+        | singleton(RecoverySucceeded)
+        | singleton(RecoveryFailed)
+        | singleton(LockChanged)
+        | singleton(RecoveryProbeCompleted)
+        | singleton(LightRegistered)
+    end
+  end
+end

data/sig/{_private/stoplight → stoplight}/domain/tracker/recovery_probe.rbs

@@ -1,24 +1,28 @@
 module Stoplight
   module Domain
     module Tracker
-      class RecoveryProbe < Base
+      class RecoveryProbe
         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
+        attr_reader emitter: Telemetry::Emitter
 
         def initialize: (
           config: Config,
           traffic_recovery: _TrafficRecovery,
-          notifiers: Array[state_transition_notifier],
           metrics_store: _MetricsStore,
           state_store: _StateStore,
+          emitter: Telemetry::Emitter,
         ) -> void
 
-        def record_failure: (StandardError exception) -> void
-        def record_success: -> void
-        def recover: -> void
+        def record_failure: (StandardError exception, duration_ms: Float) -> void
+        def record_success: (duration_ms: Float) -> void
+
+        private
+
+        def recover: (duration_ms: Float, exception: StandardError?) -> void
+        def transition: (to_color: color) -> bool
       end
     end
   end

data/sig/{_private/stoplight → stoplight}/domain/tracker/request.rbs

@@ -1,19 +1,19 @@
 module Stoplight
   module Domain
     module Tracker
-      class Request < Base
+      class Request
         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
+        attr_reader emitter: Telemetry::Emitter
 
         def initialize: (
           config: Config,
           traffic_control: _TrafficControl,
-          notifiers: Array[state_transition_notifier],
           metrics_store: _MetricsStore,
           state_store: _StateStore,
+          emitter: Telemetry::Emitter,
         ) -> void
 
         def record_failure: (StandardError exception) -> void

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

@@ -3,6 +3,8 @@ module Stoplight
     module TrafficControl
       class ConsecutiveErrors
         include _TrafficControl
+
+        NAME: :consecutive_errors
       end
     end
   end

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

@@ -4,9 +4,10 @@ module Stoplight
       class ErrorRate
         include _TrafficControl
 
-        attr_reader min_requests: Integer
+        NAME: :error_rate
+        MIN_REQUESTS: Integer
 
-        def initialize: (?min_requests: Integer) -> void
+        def initialize: () -> void
       end
     end
   end

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

@@ -3,6 +3,8 @@ module Stoplight
     module TrafficRecovery
       class ConsecutiveSuccesses
         include _TrafficRecovery
+
+        NAME: :consecutive_successes
       end
     end
   end

data/sig/stoplight/domain/types.rbs

@@ -0,0 +1,25 @@
+module Stoplight
+  module Domain
+    type timestamp = Float | Integer
+    type duration_seconds = Integer
+    type duration_ms = Float
+
+    # Light Colors
+    type green = "green"
+    type yellow = "yellow"
+    type red = "red"
+    type color = green | yellow | red
+
+    # Light States
+    type unlocked = "unlocked"
+    type locked_green = "locked_green"
+    type locked_red = "locked_red"
+    type state = unlocked | locked_green | locked_red
+
+    type recovery_decision = :green | :yellow | :red
+    type error_notifier = _ErrorNotifier
+
+    # Percentage as decimal (0.0 to 1.0)
+    type percentage = Float
+  end
+end

data/sig/stoplight/error.rbs

@@ -3,13 +3,21 @@ module Stoplight
     class Base < StandardError
     end
 
+    class UnregisteredLightError < Base
+    end
+
     class ConfigurationError < Base
     end
 
     class IncorrectColor < Base
     end
 
+    class TooManySubscriptions < Base
+    end
+
     class RedLight < Base
+      EXCEPTION_MESSAGE: String
+
       attr_reader light_name: String
       attr_reader cool_off_time: Numeric
       attr_reader retry_after: Time?