breaker_machines 0.9.2-arm64-darwin

data/lib/breaker_machines/console.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # Interactive console for debugging and monitoring circuit breakers
+  class Console
+    def self.start
+      new.run
+    end
+
+    def initialize
+      @running = true
+    end
+
+    def run
+      print_header
+      print_help if BreakerMachines::Registry.instance.all_circuits.empty?
+
+      while @running
+        print_prompt
+        command = gets&.chomp
+        break unless command
+
+        process_command(command)
+      end
+
+      puts "\nExiting BreakerMachines Console..."
+    end
+
+    private
+
+    def print_header
+      puts "\n#{'=' * 60}"
+      puts "BreakerMachines Console v#{BreakerMachines::VERSION}"
+      puts '=' * 60
+      puts "Type 'help' for available commands"
+      puts
+    end
+
+    def print_help
+      puts <<~HELP
+        Available commands:
+          list         - List all circuits
+          stats        - Show summary statistics
+          show <name>  - Show details for circuits with given name
+          events <name> [limit] - Show event log for circuit
+          reset <name> - Reset circuit(s) to closed state
+          force_open <name>  - Force circuit to open state
+          force_close <name> - Force circuit to closed state
+          report       - Generate full report
+          cleanup      - Remove dead circuit references
+          refresh      - Refresh display
+          help         - Show this help
+          exit/quit    - Exit console
+
+      HELP
+    end
+
+    def print_prompt
+      print '> '
+    end
+
+    def process_command(command)
+      parts = command.split
+      cmd = parts[0]&.downcase
+      args = parts[1..]
+
+      case cmd
+      when 'help', '?'
+        print_help
+      when 'list', 'ls'
+        list_circuits
+      when 'stats'
+        show_stats
+      when 'show'
+        show_circuit(args[0])
+      when 'events'
+        show_events(args[0], args[1]&.to_i || 10)
+      when 'reset'
+        reset_circuit(args[0])
+      when 'force_open', 'open'
+        force_open_circuit(args[0])
+      when 'force_close', 'close'
+        force_close_circuit(args[0])
+      when 'report'
+        generate_report
+      when 'cleanup'
+        cleanup_registry
+      when 'refresh', 'clear'
+        system('clear') || system('cls')
+        print_header
+      when 'exit', 'quit', 'q'
+        @running = false
+      else
+        puts "Unknown command: #{cmd}. Type 'help' for available commands."
+      end
+    end
+
+    def list_circuits
+      circuits = BreakerMachines::Registry.instance.all_circuits
+
+      if circuits.empty?
+        puts 'No circuits registered.'
+        return
+      end
+
+      puts "\nRegistered Circuits:"
+      puts '-' * 60
+      printf "%-20s %-12s %-10s %-10s %s\n", 'Name', 'State', 'Failures', 'Successes', 'Last Error'
+      puts '-' * 60
+
+      circuits.each do |circuit|
+        stats = circuit.stats
+        error_info = circuit.last_error ? circuit.last_error.class.name : '-'
+
+        printf "%-20s %-12s %-10d %-10d %s\n",
+               circuit.name,
+               colorize_state(stats.state),
+               stats.failure_count,
+               stats.success_count,
+               error_info
+      end
+
+      puts '-' * 60
+      puts "Total: #{circuits.size} circuit(s)"
+      puts
+    end
+
+    def show_stats
+      stats = BreakerMachines::Registry.instance.stats_summary
+
+      puts "\nCircuit Statistics:"
+      puts '-' * 40
+      puts "Total circuits: #{stats[:total]}"
+      puts "\nBy State:"
+      stats[:by_state].each do |state, count|
+        puts "  #{colorize_state(state)}: #{count}"
+      end
+
+      puts "\nBy Name:"
+      stats[:by_name].each do |name, count|
+        puts "  #{name}: #{count} instance(s)"
+      end
+      puts
+    end
+
+    def show_circuit(name)
+      if name.nil?
+        puts 'Usage: show <circuit_name>'
+        return
+      end
+
+      circuits = BreakerMachines::Registry.instance.find_by_name(name.to_sym)
+
+      if circuits.empty?
+        puts "No circuits found with name: #{name}"
+        return
+      end
+
+      circuits.each_with_index do |circuit, index|
+        puts "\n#{'-' * 60}"
+        puts "Circuit ##{index + 1}: #{circuit.name}"
+        puts '-' * 60
+
+        puts circuit.summary
+        puts
+
+        stats = circuit.stats
+        config = circuit.configuration
+
+        puts "Current State: #{colorize_state(stats.state)}"
+        puts "Failure Count: #{stats.failure_count} / #{config[:failure_threshold]}"
+        puts "Success Count: #{stats.success_count}"
+
+        if stats.opened_at
+          puts "Opened At: #{Time.at(stats.opened_at)}"
+          reset_time = Time.at(stats.opened_at + config[:reset_timeout])
+          puts "Reset At: #{reset_time} (in #{(reset_time - Time.now).to_i}s)"
+        end
+
+        if circuit.last_error
+          error_info = circuit.last_error_info
+          puts "\nLast Error:"
+          puts "  Class: #{error_info.error_class}"
+          puts "  Message: #{error_info.message}"
+          puts "  Time: #{Time.at(error_info.occurred_at)}"
+        end
+
+        puts "\nConfiguration:"
+        puts "  Failure Threshold: #{config[:failure_threshold]}"
+        puts "  Failure Window: #{config[:failure_window]}s"
+        puts "  Reset Timeout: #{config[:reset_timeout]}s"
+        puts "  Success Threshold: #{config[:success_threshold]}"
+        puts "  Half-Open Calls: #{config[:half_open_calls]}"
+      end
+      puts
+    end
+
+    def show_events(name, limit)
+      if name.nil?
+        puts 'Usage: events <circuit_name> [limit]'
+        return
+      end
+
+      circuits = BreakerMachines::Registry.instance.find_by_name(name.to_sym)
+
+      if circuits.empty?
+        puts "No circuits found with name: #{name}"
+        return
+      end
+
+      circuits.each do |circuit|
+        events = circuit.event_log(limit: limit)
+
+        puts "\nEvent Log for #{circuit.name} (last #{limit} events):"
+        puts '-' * 80
+
+        if events.empty?
+          puts 'No events recorded.'
+        else
+          printf "%-20s %-15s %-10s %-20s %s\n", 'Timestamp', 'Type', 'Duration', 'Error', 'Details'
+          puts '-' * 80
+
+          events.each do |event|
+            timestamp = Time.at(event[:timestamp]).strftime('%Y-%m-%d %H:%M:%S')
+            type = colorize_event_type(event[:type])
+            duration = event[:duration_ms] ? "#{event[:duration_ms]}ms" : '-'
+            error = event[:error_class] || '-'
+            details = event[:new_state] ? "→ #{event[:new_state]}" : ''
+
+            printf "%-20s %-15s %-10s %-20s %s\n", timestamp, type, duration, error, details
+          end
+        end
+      end
+      puts
+    end
+
+    def reset_circuit(name)
+      if name.nil?
+        puts 'Usage: reset <circuit_name>'
+        return
+      end
+
+      circuits = BreakerMachines::Registry.instance.find_by_name(name.to_sym)
+
+      if circuits.empty?
+        puts "No circuits found with name: #{name}"
+        return
+      end
+
+      circuits.each do |circuit|
+        circuit.reset
+        puts "Reset circuit: #{circuit.name} (now #{circuit.status_name})"
+      end
+    end
+
+    def force_open_circuit(name)
+      if name.nil?
+        puts 'Usage: force_open <circuit_name>'
+        return
+      end
+
+      circuits = BreakerMachines::Registry.instance.find_by_name(name.to_sym)
+
+      if circuits.empty?
+        puts "No circuits found with name: #{name}"
+        return
+      end
+
+      circuits.each do |circuit|
+        circuit.force_open
+        puts "Forced open circuit: #{circuit.name} (now #{circuit.status_name})"
+      end
+    end
+
+    def force_close_circuit(name)
+      if name.nil?
+        puts 'Usage: force_close <circuit_name>'
+        return
+      end
+
+      circuits = BreakerMachines::Registry.instance.find_by_name(name.to_sym)
+
+      if circuits.empty?
+        puts "No circuits found with name: #{name}"
+        return
+      end
+
+      circuits.each do |circuit|
+        circuit.force_close
+        puts "Forced close circuit: #{circuit.name} (now #{circuit.status_name})"
+      end
+    end
+
+    def generate_report
+      report = BreakerMachines::Registry.instance.detailed_report
+
+      puts "\nFull Circuit Report"
+      puts '=' * 80
+      puts "Generated at: #{Time.now}"
+      puts "Total circuits: #{report.size}"
+      puts '=' * 80
+
+      report.each do |circuit_data|
+        puts "\nCircuit: #{circuit_data[:name]}"
+        puts JSON.pretty_generate(circuit_data)
+        puts '-' * 80
+      end
+    end
+
+    def cleanup_registry
+      before = BreakerMachines::Registry.instance.all_circuits.size
+      BreakerMachines::Registry.instance.cleanup_dead_references
+      after = BreakerMachines::Registry.instance.all_circuits.size
+
+      removed = before - after
+      puts "Cleaned up #{removed} dead circuit reference(s)."
+    end
+
+    def colorize_state(state)
+      case state
+      when :closed
+        "\e[32m#{state}\e[0m" # Green
+      when :open
+        "\e[31m#{state}\e[0m"    # Red
+      when :half_open
+        "\e[33m#{state}\e[0m"    # Yellow
+      else
+        state.to_s
+      end
+    end
+
+    def colorize_event_type(type)
+      case type
+      when :success
+        "\e[32m#{type}\e[0m"     # Green
+      when :failure
+        "\e[31m#{type}\e[0m"     # Red
+      when :state_change
+        "\e[36m#{type}\e[0m"     # Cyan
+      else
+        type.to_s
+      end
+    end
+  end
+end

data/lib/breaker_machines/coordinated_circuit.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # CoordinatedCircuit is a base class for circuits that need coordinated state management.
+  # It replaces the standard StateManagement module with CoordinatedStateManagement
+  # to enable state transitions based on other circuits' states.
+  class CoordinatedCircuit < Circuit
+    include Circuit::CoordinatedStateManagement
+  end
+end

data/lib/breaker_machines/dsl/cascading_circuit_builder.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module DSL
+    # Builder for cascading circuit breaker configuration
+    class CascadingCircuitBuilder < CircuitBuilder
+      def cascades_to(*circuit_names)
+        @config[:cascades_to] = circuit_names.flatten
+      end
+
+      def emergency_protocol(protocol_name)
+        @config[:emergency_protocol] = protocol_name
+      end
+
+      def on_cascade(&block)
+        @config[:on_cascade] = block
+      end
+    end
+  end
+end

data/lib/breaker_machines/dsl/circuit_builder.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module DSL
+    # DSL builder for configuring circuit breakers with a fluent interface
+    class CircuitBuilder
+      attr_reader :config
+
+      def initialize
+        @config = {
+          failure_threshold: 5,
+          failure_window: 60.seconds,
+          success_threshold: 1,
+          timeout: nil,
+          reset_timeout: 60.seconds,
+          half_open_calls: 1,
+          exceptions: [StandardError],
+          storage: nil,
+          metrics: nil,
+          fallback: nil,
+          on_open: nil,
+          on_close: nil,
+          on_half_open: nil,
+          on_reject: nil,
+          notifications: [],
+          fiber_safe: BreakerMachines.config.fiber_safe
+        }
+      end
+
+      def threshold(failures: nil, failure_rate: nil, minimum_calls: nil, within: 60.seconds, successes: nil)
+        if failure_rate
+          # Rate-based threshold
+          validate_failure_rate!(failure_rate)
+          validate_positive_integer!(:minimum_calls, minimum_calls) if minimum_calls
+
+          @config[:failure_rate] = failure_rate
+          @config[:minimum_calls] = minimum_calls || 5
+          @config[:use_rate_threshold] = true
+        elsif failures
+          # Absolute count threshold (existing behavior)
+          validate_positive_integer!(:failures, failures)
+          @config[:failure_threshold] = failures
+          @config[:use_rate_threshold] = false
+        end
+
+        validate_positive_integer!(:within, within.to_i)
+        @config[:failure_window] = within.to_i
+
+        return unless successes
+
+        validate_positive_integer!(:successes, successes)
+        @config[:success_threshold] = successes
+      end
+
+      def reset_after(duration, jitter: nil)
+        validate_positive_integer!(:duration, duration.to_i)
+        @config[:reset_timeout] = duration.to_i
+
+        return unless jitter
+
+        validate_jitter!(jitter)
+        @config[:reset_timeout_jitter] = jitter
+      end
+
+      def timeout(duration)
+        validate_non_negative_integer!(:timeout, duration.to_i)
+        @config[:timeout] = duration.to_i
+      end
+
+      def half_open_requests(count)
+        validate_positive_integer!(:half_open_requests, count)
+        @config[:half_open_calls] = count
+      end
+
+      def storage(backend, **options)
+        @config[:storage] = case backend
+                            when :memory
+                              Storage::Memory.new(**options)
+                            when :bucket_memory
+                              Storage::BucketMemory.new(**options)
+                            when :cache
+                              Storage::Cache.new(**options)
+                            when :null
+                              Storage::Null.new(**options)
+                            when :fallback_chain
+                              config = options.is_a?(Proc) ? options.call(timeout: 5) : options
+                              Storage::FallbackChain.new(config)
+                            when Class
+                              backend.new(**options)
+                            else
+                              backend
+                            end
+      end
+
+      def metrics(recorder = nil, &block)
+        @config[:metrics] = recorder || block
+      end
+
+      def fallback(value = nil, &block)
+        raise ArgumentError, 'Fallback requires either a value or a block' if value.nil? && !block_given?
+
+        fallback_value = block || value
+
+        if @config[:fallback].is_a?(Array)
+          @config[:fallback] << fallback_value
+        elsif @config[:fallback]
+          @config[:fallback] = [@config[:fallback], fallback_value]
+        else
+          @config[:fallback] = fallback_value
+        end
+      end
+
+      def on_open(&block)
+        @config[:on_open] = block
+      end
+
+      def on_close(&block)
+        @config[:on_close] = block
+      end
+
+      def on_half_open(&block)
+        @config[:on_half_open] = block
+      end
+
+      def on_reject(&block)
+        @config[:on_reject] = block
+      end
+
+      # Configure hedged requests
+      def hedged(&)
+        if block_given?
+          hedged_builder = DSL::HedgedBuilder.new(@config)
+          hedged_builder.instance_eval(&)
+        else
+          @config[:hedged_requests] = true
+        end
+      end
+
+      # Configure multiple backends
+      def backends(*backend_list)
+        @config[:backends] = backend_list.flatten
+      end
+
+      # Configure parallel fallback execution
+      def parallel_fallback(fallback_list)
+        @config[:fallback] = DSL::ParallelFallbackWrapper.new(fallback_list)
+      end
+
+      def notify(service, url = nil, events: %i[open close], **options)
+        notification = {
+          via: service,
+          url: url,
+          events: Array(events),
+          options: options
+        }
+        @config[:notifications] << notification
+      end
+
+      def handle(*exceptions)
+        @config[:exceptions] = exceptions
+      end
+
+      def fiber_safe(enabled = true) # rubocop:disable Style/OptionalBooleanParameter
+        @config[:fiber_safe] = enabled
+      end
+
+      def max_concurrent(limit)
+        validate_positive_integer!(:max_concurrent, limit)
+        @config[:max_concurrent] = limit
+      end
+
+      # Advanced features
+      def parallel_calls(count, timeout: nil)
+        @config[:parallel_calls] = count
+        @config[:parallel_timeout] = timeout
+      end
+
+      private
+
+      def validate_positive_integer!(name, value)
+        return if value.is_a?(Integer) && value.positive?
+
+        raise BreakerMachines::ConfigurationError,
+              "#{name} must be a positive integer, got: #{value.inspect}"
+      end
+
+      def validate_non_negative_integer!(name, value)
+        return if value.is_a?(Integer) && value >= 0
+
+        raise BreakerMachines::ConfigurationError,
+              "#{name} must be a non-negative integer, got: #{value.inspect}"
+      end
+
+      def validate_failure_rate!(rate)
+        return if rate.is_a?(Numeric) && rate >= 0.0 && rate <= 1.0
+
+        raise BreakerMachines::ConfigurationError,
+              "failure_rate must be between 0.0 and 1.0, got: #{rate.inspect}"
+      end
+
+      def validate_jitter!(jitter)
+        return if jitter.is_a?(Numeric) && jitter >= 0.0 && jitter <= 1.0
+
+        raise BreakerMachines::ConfigurationError,
+              "jitter must be between 0.0 and 1.0 (0% to 100%), got: #{jitter.inspect}"
+      end
+    end
+  end
+end

data/lib/breaker_machines/dsl/hedged_builder.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module DSL
+    # Builder for hedged request configuration
+    class HedgedBuilder
+      def initialize(config)
+        @config = config
+        @config[:hedged_requests] = true
+      end
+
+      def delay(milliseconds)
+        @config[:hedging_delay] = milliseconds
+      end
+
+      def max_requests(count)
+        @config[:max_hedged_requests] = count
+      end
+    end
+  end
+end

data/lib/breaker_machines/dsl/parallel_fallback_wrapper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module DSL
+    # Wrapper to indicate parallel execution for fallbacks
+    class ParallelFallbackWrapper
+      attr_reader :fallbacks
+
+      def initialize(fallbacks)
+        @fallbacks = fallbacks
+      end
+
+      def call(error)
+        # This will be handled by the circuit's fallback mechanism
+        # to execute fallbacks in parallel
+        raise NotImplementedError, 'ParallelFallbackWrapper should be handled by Circuit'
+      end
+    end
+  end
+end