fluyenta-ruby 0.1.14

data/lib/brainzlab/testing.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+require_relative 'testing/event_store'
+require_relative 'testing/helpers'
+require_relative 'testing/matchers'
+
+module BrainzLab
+  # Testing utilities for BrainzLab SDK
+  #
+  # Provides helpers for stubbing SDK calls, capturing events,
+  # and custom matchers for RSpec/Minitest.
+  #
+  # @example Usage in RSpec
+  #   # spec/rails_helper.rb or spec/spec_helper.rb
+  #   require 'brainzlab/testing'
+  #
+  #   RSpec.configure do |config|
+  #     config.include BrainzLab::Testing::Helpers
+  #   end
+  #
+  # @example Usage in Minitest
+  #   # test/test_helper.rb
+  #   require 'brainzlab/testing'
+  #
+  #   class ActiveSupport::TestCase
+  #     include BrainzLab::Testing::Helpers
+  #   end
+  #
+  module Testing
+    class << self
+      # Global event store for capturing events during tests
+      def event_store
+        @event_store ||= EventStore.new
+      end
+
+      # Reset the event store (called between tests)
+      def reset!
+        @event_store = EventStore.new
+      end
+
+      # Check if testing mode is active
+      def enabled?
+        @enabled == true
+      end
+
+      # Enable testing mode (stubs all SDK calls)
+      def enable!
+        return if @enabled
+
+        @enabled = true
+        install_stubs!
+      end
+
+      # Disable testing mode
+      def disable!
+        return unless @enabled
+
+        @enabled = false
+        remove_stubs!
+      end
+
+      private
+
+      def install_stubs!
+        # Stub Flux (events/metrics)
+        stub_flux!
+
+        # Stub Recall (logging)
+        stub_recall!
+
+        # Stub Reflex (error tracking)
+        stub_reflex!
+
+        # Stub Pulse (APM/tracing)
+        stub_pulse!
+
+        # Stub Signal (alerts/notifications)
+        stub_signal!
+
+        # Stub other modules
+        stub_beacon!
+        stub_nerve!
+        stub_dendrite!
+        stub_sentinel!
+        stub_synapse!
+        stub_cortex!
+        stub_vault!
+        stub_vision!
+      end
+
+      def remove_stubs!
+        # Reset all modules to restore original behavior
+        BrainzLab.reset_configuration!
+      end
+
+      def stub_flux!
+        # Store original methods
+        @original_flux_track = BrainzLab::Flux.method(:track)
+
+        # Replace with capturing versions
+        BrainzLab::Flux.define_singleton_method(:track) do |name, properties = {}|
+          BrainzLab::Testing.event_store.record_event(name, properties)
+        end
+
+        BrainzLab::Flux.define_singleton_method(:track_for_user) do |user, name, properties = {}|
+          user_id = user.respond_to?(:id) ? user.id.to_s : user.to_s
+          BrainzLab::Testing.event_store.record_event(name, properties.merge(user_id: user_id))
+        end
+
+        # Stub metrics
+        %i[gauge increment decrement distribution histogram timing set].each do |method|
+          BrainzLab::Flux.define_singleton_method(method) do |name, value = nil, **opts|
+            BrainzLab::Testing.event_store.record_metric(method, name, value, opts)
+          end
+        end
+
+        BrainzLab::Flux.define_singleton_method(:measure) do |name, **opts, &block|
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = block.call
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+          BrainzLab::Testing.event_store.record_metric(:distribution, name, duration_ms, opts.merge(unit: 'ms'))
+          result
+        end
+
+        BrainzLab::Flux.define_singleton_method(:flush!) { true }
+      end
+
+      def stub_recall!
+        %i[debug info warn error fatal].each do |level|
+          BrainzLab::Recall.define_singleton_method(level) do |message, **data|
+            BrainzLab::Testing.event_store.record_log(level, message, data)
+          end
+        end
+
+        BrainzLab::Recall.define_singleton_method(:log) do |level, message, **data|
+          BrainzLab::Testing.event_store.record_log(level, message, data)
+        end
+
+        BrainzLab::Recall.define_singleton_method(:time) do |label, **data, &block|
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = block.call
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(1)
+          BrainzLab::Testing.event_store.record_log(:info, "#{label} (#{duration_ms}ms)", data.merge(duration_ms: duration_ms))
+          result
+        end
+
+        BrainzLab::Recall.define_singleton_method(:flush) { true }
+      end
+
+      def stub_reflex!
+        BrainzLab::Reflex.define_singleton_method(:capture) do |exception, **context|
+          BrainzLab::Testing.event_store.record_error(exception, context)
+        end
+
+        BrainzLab::Reflex.define_singleton_method(:capture_message) do |message, level: :error, **context|
+          BrainzLab::Testing.event_store.record_error_message(message, level, context)
+        end
+      end
+
+      def stub_pulse!
+        # Stub tracing methods
+        BrainzLab::Pulse.define_singleton_method(:start_trace) do |name, **opts|
+          BrainzLab::Testing.event_store.record_trace(name, opts.merge(action: :start))
+          { trace_id: 'test-trace-id-12345', name: name }
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:finish_trace) do |**opts|
+          BrainzLab::Testing.event_store.record_trace('finish', opts.merge(action: :finish))
+          true
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:span) do |name, **opts, &block|
+          BrainzLab::Testing.event_store.record_trace(name, opts.merge(type: :span))
+          block&.call
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:record_trace) do |name, **opts|
+          BrainzLab::Testing.event_store.record_trace(name, opts)
+          true
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:record_span) do |**opts|
+          BrainzLab::Testing.event_store.record_trace(opts[:name], opts)
+          true
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:record_metric) do |name, **opts|
+          BrainzLab::Testing.event_store.record_metric(opts[:kind] || :gauge, name, opts[:value], tags: opts[:tags] || {})
+          true
+        end
+
+        # Stub metric convenience methods
+        %i[gauge counter histogram].each do |method|
+          BrainzLab::Pulse.define_singleton_method(method) do |name, value, tags: {}|
+            BrainzLab::Testing.event_store.record_metric(method, name, value, tags: tags)
+            true
+          end
+        end
+
+        # Stub distributed tracing methods
+        BrainzLab::Pulse.define_singleton_method(:inject) do |headers, **opts|
+          headers['traceparent'] = '00-test-trace-id-12345-test-span-id-67890-01'
+          headers
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:extract) do |headers|
+          BrainzLab::Pulse::Propagation::Context.new(
+            trace_id: 'test-trace-id-12345',
+            span_id: 'test-span-id-67890'
+          ) if headers['traceparent']
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:extract!) do |headers|
+          BrainzLab::Pulse.extract(headers)
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:propagation_context) do
+          BrainzLab::Pulse::Propagation::Context.new(
+            trace_id: 'test-trace-id-12345',
+            span_id: 'test-span-id-67890'
+          )
+        end
+
+        BrainzLab::Pulse.define_singleton_method(:child_context) do
+          BrainzLab::Pulse::Propagation::Context.new(
+            trace_id: 'test-trace-id-12345',
+            span_id: SecureRandom.hex(8)
+          )
+        end
+      end
+
+      def stub_signal!
+        BrainzLab::Signal.define_singleton_method(:alert) do |name, message, severity: :warning, channels: nil, data: {}|
+          BrainzLab::Testing.event_store.record_alert(name, message, severity, channels, data)
+        end
+
+        BrainzLab::Signal.define_singleton_method(:notify) do |channel, message, title: nil, data: {}|
+          BrainzLab::Testing.event_store.record_notification(channel, message, title, data)
+        end
+
+        BrainzLab::Signal.define_singleton_method(:trigger) do |rule_name, context = {}|
+          BrainzLab::Testing.event_store.record_trigger(rule_name, context)
+        end
+
+        BrainzLab::Signal.define_singleton_method(:test!) { true }
+      end
+
+      def stub_beacon!
+        return unless defined?(BrainzLab::Beacon)
+
+        BrainzLab::Beacon.define_singleton_method(:create_http_monitor) { |*| { id: 'test-monitor-1', status: 'created' } }
+        BrainzLab::Beacon.define_singleton_method(:create_ssl_monitor) { |*| { id: 'test-monitor-2', status: 'created' } }
+        BrainzLab::Beacon.define_singleton_method(:create_tcp_monitor) { |*| { id: 'test-monitor-3', status: 'created' } }
+        BrainzLab::Beacon.define_singleton_method(:create_dns_monitor) { |*| { id: 'test-monitor-4', status: 'created' } }
+        BrainzLab::Beacon.define_singleton_method(:list) { [] }
+        BrainzLab::Beacon.define_singleton_method(:get) { |_id| nil }
+        BrainzLab::Beacon.define_singleton_method(:update) { |*| true }
+        BrainzLab::Beacon.define_singleton_method(:delete) { |_id| true }
+        BrainzLab::Beacon.define_singleton_method(:pause) { |_id| true }
+        BrainzLab::Beacon.define_singleton_method(:resume) { |_id| true }
+        BrainzLab::Beacon.define_singleton_method(:history) { |*| [] }
+        BrainzLab::Beacon.define_singleton_method(:status) { { status: 'up', monitors: 0 } }
+        BrainzLab::Beacon.define_singleton_method(:all_up?) { true }
+        BrainzLab::Beacon.define_singleton_method(:incidents) { [] }
+      end
+
+      def stub_nerve!
+        return unless defined?(BrainzLab::Nerve)
+
+        BrainzLab::Nerve.define_singleton_method(:flag) { |*| false }
+        BrainzLab::Nerve.define_singleton_method(:enabled?) { |*| false }
+        BrainzLab::Nerve.define_singleton_method(:disabled?) { |*| true }
+        BrainzLab::Nerve.define_singleton_method(:variation) { |*| nil }
+        BrainzLab::Nerve.define_singleton_method(:all_flags) { {} }
+      end
+
+      def stub_dendrite!
+        return unless defined?(BrainzLab::Dendrite)
+
+        BrainzLab::Dendrite.define_singleton_method(:get) { |*| nil }
+        BrainzLab::Dendrite.define_singleton_method(:set) { |*| true }
+        BrainzLab::Dendrite.define_singleton_method(:delete) { |*| true }
+        BrainzLab::Dendrite.define_singleton_method(:all) { {} }
+      end
+
+      def stub_sentinel!
+        return unless defined?(BrainzLab::Sentinel)
+
+        BrainzLab::Sentinel.define_singleton_method(:check) { |*| { allowed: true } }
+        BrainzLab::Sentinel.define_singleton_method(:allowed?) { |*| true }
+        BrainzLab::Sentinel.define_singleton_method(:denied?) { |*| false }
+      end
+
+      def stub_synapse!
+        return unless defined?(BrainzLab::Synapse)
+
+        BrainzLab::Synapse.define_singleton_method(:publish) { |*| true }
+        BrainzLab::Synapse.define_singleton_method(:subscribe) { |*| true }
+      end
+
+      def stub_cortex!
+        return unless defined?(BrainzLab::Cortex)
+
+        BrainzLab::Cortex.define_singleton_method(:read) { |*| nil }
+        BrainzLab::Cortex.define_singleton_method(:write) { |*| true }
+        BrainzLab::Cortex.define_singleton_method(:delete) { |*| true }
+        BrainzLab::Cortex.define_singleton_method(:fetch) { |key, **opts, &block| block&.call }
+      end
+
+      def stub_vault!
+        return unless defined?(BrainzLab::Vault)
+
+        BrainzLab::Vault.define_singleton_method(:get) { |*| nil }
+        BrainzLab::Vault.define_singleton_method(:set) { |*| true }
+        BrainzLab::Vault.define_singleton_method(:delete) { |*| true }
+      end
+
+      def stub_vision!
+        return unless defined?(BrainzLab::Vision)
+
+        BrainzLab::Vision.define_singleton_method(:track_pageview) { |*| true }
+        BrainzLab::Vision.define_singleton_method(:track_event) { |*| true }
+        BrainzLab::Vision.define_singleton_method(:identify) { |*| true }
+      end
+    end
+  end
+end

data/lib/brainzlab/utilities/circuit_breaker.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  module Utilities
+    # Circuit breaker pattern implementation for resilient external calls
+    # Integrates with Flux for metrics and Reflex for error tracking
+    #
+    # States:
+    # - :closed - Normal operation, requests pass through
+    # - :open - Failing, requests are rejected immediately
+    # - :half_open - Testing, limited requests allowed to check recovery
+    #
+    # @example Basic usage
+    #   breaker = BrainzLab::Utilities::CircuitBreaker.new(
+    #     name: "external_api",
+    #     failure_threshold: 5,
+    #     recovery_timeout: 30
+    #   )
+    #
+    #   breaker.call do
+    #     external_api.request
+    #   end
+    #
+    # @example With fallback
+    #   breaker.call(fallback: -> { cached_value }) do
+    #     external_api.request
+    #   end
+    #
+    class CircuitBreaker
+      STATES = %i[closed open half_open].freeze
+
+      attr_reader :name, :state, :failure_count, :success_count, :last_failure_at
+
+      def initialize(name:, failure_threshold: 5, success_threshold: 2, recovery_timeout: 30, timeout: nil,
+                     exclude_exceptions: [])
+        @name = name
+        @failure_threshold = failure_threshold
+        @success_threshold = success_threshold
+        @recovery_timeout = recovery_timeout
+        @timeout = timeout
+        @exclude_exceptions = exclude_exceptions
+
+        @state = :closed
+        @failure_count = 0
+        @success_count = 0
+        @last_failure_at = nil
+        @mutex = Mutex.new
+      end
+
+      # Execute a block with circuit breaker protection
+      def call(fallback: nil, &)
+        check_state_transition!
+
+        case @state
+        when :open
+          track_rejected
+          raise CircuitOpenError.new(@name, failure_count: @failure_count, last_failure_at: @last_failure_at) unless fallback
+
+          fallback.respond_to?(:call) ? fallback.call : fallback
+
+        when :closed, :half_open
+          execute_with_protection(fallback, &)
+        end
+      end
+
+      # Force the circuit to a specific state
+      def force_state!(new_state)
+        unless STATES.include?(new_state)
+          raise BrainzLab::ValidationError.new(
+            "Invalid circuit breaker state: #{new_state}",
+            hint: "Valid states are: #{STATES.join(', ')}",
+            code: 'invalid_circuit_state',
+            field: 'state',
+            context: { provided: new_state, valid_values: STATES }
+          )
+        end
+
+        @mutex.synchronize do
+          @state = new_state
+          @failure_count = 0 if new_state == :closed
+          @success_count = 0 if new_state == :half_open
+        end
+
+        track_state_change(new_state)
+      end
+
+      # Reset the circuit breaker
+      def reset!
+        force_state!(:closed)
+        @last_failure_at = nil
+      end
+
+      # Get circuit status
+      def status
+        {
+          name: @name,
+          state: @state,
+          failure_count: @failure_count,
+          success_count: @success_count,
+          failure_threshold: @failure_threshold,
+          success_threshold: @success_threshold,
+          last_failure_at: @last_failure_at,
+          recovery_timeout: @recovery_timeout
+        }
+      end
+
+      # Check if circuit is allowing requests
+      def available?
+        check_state_transition!
+        @state != :open
+      end
+
+      # Class-level registry of circuit breakers
+      class << self
+        def registry
+          @registry ||= {}
+        end
+
+        def get(name)
+          registry[name.to_s]
+        end
+
+        def register(name, **)
+          registry[name.to_s] = new(name: name, **)
+        end
+
+        def call(name, **options, &)
+          breaker = get(name) || register(name, **options)
+          breaker.call(**options.slice(:fallback), &)
+        end
+
+        def reset_all!
+          registry.each_value(&:reset!)
+        end
+
+        def status_all
+          registry.transform_values(&:status)
+        end
+      end
+
+      private
+
+      def execute_with_protection(fallback, &)
+        result = if @timeout
+                   Timeout.timeout(@timeout, &)
+                 else
+                   yield
+                 end
+
+        record_success
+        result
+      rescue *excluded_exceptions
+        # Don't count excluded exceptions as failures
+        raise
+      rescue StandardError => e
+        record_failure(e)
+
+        raise unless fallback
+
+        fallback.respond_to?(:call) ? fallback.call : fallback
+      end
+
+      def record_success
+        @mutex.synchronize do
+          if @state == :half_open
+            @success_count += 1
+            transition_to(:closed) if @success_count >= @success_threshold
+          else
+            @failure_count = 0
+          end
+        end
+
+        track_success
+      end
+
+      def record_failure(error)
+        @mutex.synchronize do
+          @failure_count += 1
+          @last_failure_at = Time.now
+
+          if @state == :half_open
+            transition_to(:open)
+          elsif @failure_count >= @failure_threshold
+            transition_to(:open)
+          end
+        end
+
+        track_failure(error)
+      end
+
+      def check_state_transition!
+        return unless @state == :open && @last_failure_at
+
+        return unless Time.now - @last_failure_at >= @recovery_timeout
+
+        @mutex.synchronize do
+          transition_to(:half_open) if @state == :open
+        end
+      end
+
+      def transition_to(new_state)
+        old_state = @state
+        @state = new_state
+
+        case new_state
+        when :closed
+          @failure_count = 0
+          @success_count = 0
+        when :half_open
+          @success_count = 0
+        when :open
+          # Keep failure count for debugging
+        end
+
+        track_state_change(new_state, old_state)
+      end
+
+      def excluded_exceptions
+        @exclude_exceptions.empty? ? [] : @exclude_exceptions
+      end
+
+      # Metrics tracking
+
+      def track_success
+        return unless BrainzLab.configuration.flux_effectively_enabled?
+
+        BrainzLab::Flux.increment('circuit_breaker.success', tags: { name: @name, state: @state.to_s })
+      end
+
+      def track_failure(error)
+        return unless BrainzLab.configuration.flux_effectively_enabled?
+
+        BrainzLab::Flux.increment('circuit_breaker.failure', tags: {
+                                    name: @name,
+                                    state: @state.to_s,
+                                    error_class: error.class.name
+                                  })
+      end
+
+      def track_rejected
+        return unless BrainzLab.configuration.flux_effectively_enabled?
+
+        BrainzLab::Flux.increment('circuit_breaker.rejected', tags: { name: @name })
+      end
+
+      def track_state_change(new_state, old_state = nil)
+        return unless BrainzLab.configuration.flux_effectively_enabled?
+
+        BrainzLab::Flux.track('circuit_breaker.state_change', {
+                                name: @name,
+                                new_state: new_state.to_s,
+                                old_state: old_state&.to_s,
+                                failure_count: @failure_count
+                              })
+
+        # Also add breadcrumb for debugging
+        BrainzLab::Reflex.add_breadcrumb(
+          "Circuit '#{@name}' transitioned to #{new_state}",
+          category: 'circuit_breaker',
+          level: new_state == :open ? :warning : :info,
+          data: { name: @name, old_state: old_state, new_state: new_state }
+        )
+      end
+
+      # Error raised when circuit is open
+      # Inherits from BrainzLab::ServiceUnavailableError for structured error handling
+      class CircuitOpenError < BrainzLab::ServiceUnavailableError
+        attr_reader :circuit_name, :failure_count, :last_failure_at
+
+        def initialize(circuit_name, failure_count: nil, last_failure_at: nil)
+          @circuit_name = circuit_name
+          @failure_count = failure_count
+          @last_failure_at = last_failure_at
+
+          super(
+            "Circuit '#{circuit_name}' is open",
+            hint: 'The circuit breaker has tripped due to repeated failures. The service will be retried automatically after the recovery timeout.',
+            code: 'circuit_open',
+            service_name: circuit_name,
+            context: {
+              circuit_name: circuit_name,
+              failure_count: failure_count,
+              last_failure_at: last_failure_at&.iso8601
+            }.compact
+          )
+        end
+      end
+    end
+  end
+end