stoplight 5.8.3 → 6.0.0.rc2

data/lib/stoplight/domain/telemetry/bus.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # In-process telemetry bus
+      class Bus
+        # Value-level mirror of the +event+ union.
+        EVENT_CLASSES = [
+          RunCompleted,
+          TrafficBreached,
+          RecoveryStarted,
+          RecoverySucceeded,
+          RecoveryFailed,
+          LockChanged,
+          RecoveryProbeCompleted,
+          LightRegistered
+        ].freeze
+
+        MAX_SUBSCRIPTIONS = 1_000
+
+        def initialize(error_notifier:, max_subscriptions: MAX_SUBSCRIPTIONS)
+          @mutex = Mutex.new
+          @error_notifier = error_notifier
+          @max_subscriptions = max_subscriptions
+          @subscriptions = []
+          rebuild
+        end
+
+        def subscribe(filter = nil, &handler)
+          raise ArgumentError, "nothing to subscribe. Please, pass a block into `Telemetry#subscribe`" unless handler
+          raise ArgumentError, "filter must be nil or a Module, got #{filter.inspect}" unless filter.nil? || filter.is_a?(Module)
+          unless filter.nil? || EVENT_CLASSES.any? { |event_class| event_class <= filter }
+            raise ArgumentError, "filter #{filter.inspect} does not match any telemetry event class"
+          end
+
+          subscription = Subscription.new
+          @mutex.synchronize do
+            if @subscriptions.size >= @max_subscriptions
+              raise Stoplight::Error::TooManySubscriptions, "exceeded #{@max_subscriptions} telemetry subscriptions"
+            end
+
+            @subscriptions << [subscription, filter, handler]
+            rebuild
+          end
+          subscription
+        end
+
+        def unsubscribe(subscription)
+          @mutex.synchronize do
+            @subscriptions.reject! { |token, _, _| token.equal?(subscription) }
+            rebuild
+          end
+          nil
+        end
+
+        def subscribed?(event_class)
+          @dispatch.key?(event_class)
+        end
+
+        def publish(envelope)
+          @dispatch[envelope.payload.class]&.each do |handler|
+            handler.call(envelope)
+          rescue => error
+            begin
+              @error_notifier.call(error)
+            rescue => notifier_error
+              warn "Stoplight telemetry error_notifier raised: #{notifier_error.message}"
+            end
+          end
+          nil
+        end
+
+        # Called under @mutex. Resolves every filter (nil = firehose, module, or exact class) against the closed set of
+        # concrete classes and swaps in a frozen table - copy-on-write, so publish never sees a table mid-mutation and
+        # needs no lock.
+        private def rebuild
+          table = {} #: Hash[Class, Array[untyped]]
+          EVENT_CLASSES.each do |event_class|
+            handlers = @subscriptions.filter_map do |_, filter, handler|
+              handler if filter.nil? || event_class <= filter
+            end
+            table[event_class] = handlers.freeze unless handlers.empty?
+          end
+          @dispatch = table.freeze
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/consumer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # Consumer-only view of a telemetry bus - forwards subscribe/unsubscribe, never publish.
+      class Consumer
+        def initialize(telemetry)
+          @telemetry = telemetry
+        end
+
+        def subscribe(...) = @telemetry.subscribe(...)
+
+        def unsubscribe(...) = @telemetry.unsubscribe(...)
+      end
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/emitter.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      class Emitter
+        def initialize(bus:, clock:, system_name:, light_name:, error_notifier:)
+          @bus = bus
+          @clock = clock
+          @system_name = system_name
+          @light_name = light_name
+          @error_notifier = error_notifier
+        end
+
+        # True when any subscriber would receive this event class.
+        def subscribed?(event_class) = @bus.subscribed?(event_class)
+
+        # Emits telemetry event. A failure to build or publish it is routed to the error
+        # notifier, never to the caller - the same isolation the bus gives subscriber handlers.
+        def emit(event_class)
+          return unless subscribed?(event_class)
+
+          @bus.publish(
+            Envelope.new(
+              light_name: @light_name,
+              system_name: @system_name,
+              occurred_at: @clock.current_time,
+              payload: yield
+            )
+          )
+        rescue => error
+          notify_error(error)
+        end
+
+        private
+
+        def notify_error(error)
+          @error_notifier.call(error)
+        rescue => notifier_error
+          warn "Stoplight telemetry error_notifier raised: #{notifier_error.message}"
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/envelope.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # Wraps every published event.
+      Envelope = Data.define(
+        :system_name,
+        :light_name,
+        :occurred_at,
+        :payload
+      )
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/failure.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # Carries the live exception.
+      Failure = Data.define(
+        :exception,
+        :tracked
+      )
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/light_registered.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # Emitted once per (process instance, system, light) when the light's configuration first materializes.
+      LightRegistered = Data.define(
+        :settings
+      )
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/lock_changed.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # state_transitioned variant: manual lock override changed.
+      LockChanged = Data.define(
+        :from_color,
+        :to_color,
+        :from_state,
+        :to_state
+      )
+
+      class LockChanged
+        include StateTransitioned
+      end
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/metrics.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # The serializable subset of MetricsSnapshot.
+      Metrics = Data.define(
+        :successes,
+        :errors,
+        :consecutive_errors,
+        :consecutive_successes
+      )
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/recovery_failed.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # state_transitioned variant: recovery policy sent the light back to red.
+      RecoveryFailed = Data.define(
+        :from_color,
+        :to_color,
+        :policy,
+        :failure,
+        :metrics
+      )
+
+      class RecoveryFailed
+        include StateTransitioned
+      end
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/recovery_probe_completed.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # Emitted for every recovery probe (a run executed while yellow, under the recovery lock).
+      RecoveryProbeCompleted = Data.define(
+        :outcome,
+        :duration_ms,
+        :failure,
+        :progress
+      )
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/recovery_started.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # state_transitioned variant: cool-off elapsed and the first probe explicitly entered recovery.
+      RecoveryStarted = Data.define(
+        :from_color,
+        :to_color,
+        :breached_at
+      )
+
+      class RecoveryStarted
+        include StateTransitioned
+      end
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/recovery_succeeded.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # state_transitioned variant: recovery policy resumed traffic.
+      RecoverySucceeded = Data.define(
+        :from_color,
+        :to_color,
+        :policy,
+        :metrics
+      )
+
+      class RecoverySucceeded
+        include StateTransitioned
+      end
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/run_completed.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # Emitted for every Light#run.
+      RunCompleted = Data.define(
+        :outcome,
+        :color,
+        :duration_ms,
+        :failure,
+        :fallback_used,
+        :retry_after
+      )
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/run_recorder.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # Builds and emits RunCompleted events for one light color.
+      #
+      # @api private
+      class RunRecorder
+        def initialize(emitter:, color:)
+          @emitter = emitter
+          @color = color
+        end
+
+        # True when any subscriber would receive a RunCompleted event.
+        def subscribed? = @emitter.subscribed?(RunCompleted)
+
+        def record_success(duration_ms:, error: nil)
+          emit(
+            outcome: :success,
+            duration_ms:,
+            failure: error && Failure.new(exception: error, tracked: false),
+            fallback_used: false,
+            retry_after: nil
+          )
+        end
+
+        def record_failure(error, duration_ms:, fallback_used:)
+          emit(
+            outcome: :failure,
+            duration_ms:,
+            failure: Failure.new(exception: error, tracked: true),
+            fallback_used:,
+            retry_after: nil
+          )
+        end
+
+        def record_blocked(fallback_used:, retry_after:)
+          emit(
+            outcome: :blocked,
+            duration_ms: nil,
+            failure: nil,
+            fallback_used:,
+            retry_after:
+          )
+        end
+
+        private
+
+        def emit(outcome:, duration_ms:, failure:, fallback_used:, retry_after:)
+          @emitter.emit(RunCompleted) do
+            RunCompleted.new(outcome:, color: @color, duration_ms:, failure:, fallback_used:, retry_after:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/settings.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # The serializable subset of a light's configuration.
+      Settings = Data.define(
+        :cool_off_time,
+        :threshold,
+        :recovery_threshold,
+        :window_size,
+        :tracked_errors,
+        :skipped_errors,
+        :traffic_control,
+        :traffic_control_params,
+        :traffic_recovery,
+        :traffic_recovery_params
+      )
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/state_transitioned.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # Runtime name for the +state_transitioned+ union: a marker module included by every transition variant.
+      module StateTransitioned
+      end
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/subscription.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # Opaque, single-use token returned by Telemetry#subscribe and accepted by Telemetry#unsubscribe.
+      class Subscription
+      end
+    end
+  end
+end

data/lib/stoplight/domain/telemetry/traffic_breached.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Stoplight
+  module Domain
+    module Telemetry
+      # state_transitioned variant: traffic control tripped the light.
+      TrafficBreached = Data.define(
+        :from_color,
+        :to_color,
+        :policy,
+        :failure,
+        :metrics
+      )
+
+      class TrafficBreached
+        include StateTransitioned
+      end
+    end
+  end
+end

data/lib/stoplight/domain/tracker/recovery_probe.rb

@@ -4,54 +4,98 @@ module Stoplight
   module Domain
     module Tracker
       class RecoveryProbe
-        def initialize(traffic_recovery:, notifiers:, config:, metrics_store:, state_store:)
+        def initialize(traffic_recovery:, config:, metrics_store:, state_store:, emitter:)
           @traffic_recovery = traffic_recovery
-          @notifiers = notifiers
           @config = config
           @metrics_store = metrics_store
           @state_store = state_store
+          @emitter = emitter
         end
 
-        # @param exception [Exception]
-        def record_failure(exception)
+        def record_failure(exception, duration_ms:)
           metrics_store.record_failure(exception)
 
-          recover
+          recover(duration_ms:, exception:)
         end
 
-        def record_success
+        def record_success(duration_ms:)
           metrics_store.record_success
 
-          recover
+          recover(duration_ms:, exception: nil)
         end
 
         private
 
         attr_reader :traffic_recovery
-        attr_reader :notifiers
         attr_reader :config
         attr_reader :metrics_store
         attr_reader :state_store
+        attr_reader :emitter
 
-        def recover
+        def recover(duration_ms:, exception:)
           recovery_metrics = metrics_store.metrics_snapshot
+
+          emitter.emit(Telemetry::RecoveryProbeCompleted) do
+            failure = exception ? Telemetry::Failure.new(exception:, tracked: true) : nil
+            Telemetry::RecoveryProbeCompleted.new(
+              outcome: failure ? :failure : :success,
+              duration_ms:,
+              failure:,
+              progress: Telemetry::Metrics.new(
+                successes: recovery_metrics.successes,
+                errors: recovery_metrics.errors,
+                consecutive_errors: recovery_metrics.consecutive_errors,
+                consecutive_successes: recovery_metrics.consecutive_successes
+              )
+            )
+          end
+
           recovery_result = traffic_recovery.determine_color(config, recovery_metrics)
 
           return if recovery_result == TrafficRecovery::YELLOW
 
-          from_color, to_color = case recovery_result
-          when TrafficRecovery::GREEN then [Color::YELLOW, Color::GREEN]
-          when TrafficRecovery::RED then [Color::YELLOW, Color::RED]
+          case recovery_result
+          when TrafficRecovery::GREEN
+            to_color = Color::GREEN
+            if transition(to_color:)
+              emitter.emit(Telemetry::RecoverySucceeded) do
+                Telemetry::RecoverySucceeded.new(from_color: Color::YELLOW, to_color:,
+                  policy: traffic_recovery.name,
+                  metrics: Telemetry::Metrics.new(
+                    successes: recovery_metrics.successes,
+                    errors: recovery_metrics.errors,
+                    consecutive_errors: recovery_metrics.consecutive_errors,
+                    consecutive_successes: recovery_metrics.consecutive_successes
+                  ))
+              end
+            end
+          when TrafficRecovery::RED
+            to_color = Color::RED
+            if transition(to_color:)
+              emitter.emit(Telemetry::RecoveryFailed) do
+                Telemetry::RecoveryFailed.new(
+                  from_color: Color::YELLOW,
+                  to_color:,
+                  policy: traffic_recovery.name,
+                  failure: exception ? Telemetry::Failure.new(exception:, tracked: true) : nil,
+                  metrics: Telemetry::Metrics.new(
+                    successes: recovery_metrics.successes,
+                    errors: recovery_metrics.errors,
+                    consecutive_errors: recovery_metrics.consecutive_errors,
+                    consecutive_successes: recovery_metrics.consecutive_successes
+                  )
+                )
+              end
+            end
           else
             raise "recovery strategy returned unexpected color: #{recovery_result}"
           end
+        end
 
-          state_store.transition_to_color(to_color)
+        def transition(to_color:)
+          return false unless state_store.transition_to_color(to_color)
           metrics_store.clear
-          info = LightInfo.new(name: config.name)
-          notifiers.each do |notifier|
-            notifier.notify(info, from_color, to_color, nil)
-          end
+          true
         end
       end
     end

data/lib/stoplight/domain/tracker/request.rb

@@ -10,17 +10,16 @@ module Stoplight
       #
       # @api private
       class Request
-        def initialize(traffic_control:, notifiers:, config:, metrics_store:, state_store:)
+        def initialize(traffic_control:, config:, metrics_store:, state_store:, emitter:)
           @traffic_control = traffic_control
-          @notifiers = notifiers
           @config = config
           @metrics_store = metrics_store
           @state_store = state_store
+          @emitter = emitter
         end
 
         def record_failure(exception)
-          metrics_store.record_failure(exception)
-          metrics = metrics_store.metrics_snapshot
+          metrics = metrics_store.record_failure(exception)
 
           transition_to_red(exception, metrics:)
         end
@@ -30,19 +29,29 @@ module Stoplight
         private
 
         attr_reader :traffic_control
-        attr_reader :notifiers
         attr_reader :config
         attr_reader :metrics_store
         attr_reader :state_store
+        attr_reader :emitter
 
         def transition_to_red(exception, metrics:)
           if traffic_control.stop_traffic?(config, metrics)
             # Returns true only if not yet in red therefore preventing
             # duplicate notifications
             if state_store.transition_to_color(Color::RED)
-              info = LightInfo.new(name: config.name)
-              notifiers.each do |notifier|
-                notifier.notify(info, Color::GREEN, Color::RED, exception)
+              emitter.emit(Telemetry::TrafficBreached) do
+                Telemetry::TrafficBreached.new(
+                  from_color: Color::GREEN,
+                  to_color: Color::RED,
+                  policy: traffic_control.name,
+                  failure: Telemetry::Failure.new(exception:, tracked: true),
+                  metrics: Telemetry::Metrics.new(
+                    successes: metrics.successes,
+                    errors: metrics.errors,
+                    consecutive_errors: metrics.consecutive_errors,
+                    consecutive_successes: metrics.consecutive_successes
+                  )
+                )
               end
             end
           end

data/lib/stoplight/domain/traffic_control/consecutive_errors.rb

@@ -27,11 +27,13 @@ module Stoplight
       # Will switch to red only if 5 consecutive failures occur regardless of the time window
       # @api private
       class ConsecutiveErrors
+        NAME = :consecutive_errors
+
         def check_compatibility(config)
-          if config.threshold <= 0
-            CompatibilityResult.incompatible("`threshold` should be bigger than 0")
-          elsif !config.threshold.is_a?(Integer)
+          if !config.threshold.is_a?(Integer)
             CompatibilityResult.incompatible("`threshold` should be an integer")
+          elsif config.threshold <= 0
+            CompatibilityResult.incompatible("`threshold` should be bigger than 0")
           else
             CompatibilityResult.compatible
           end
@@ -41,9 +43,17 @@ module Stoplight
           metrics.consecutive_errors >= config.threshold
         end
 
+        def name = NAME.to_s
+
+        def hash = self.class.hash
+
         def ==(other)
           other.is_a?(self.class)
         end
+
+        def eql?(other)
+          self == other
+        end
       end
     end
   end