breaker_machines 0.1.0

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[: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/dsl.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # DSL module for adding circuit breakers to classes
+  #
+  # This module uses WeakRef to track instances that include the DSL.
+  # Why? In long-running applications (web servers, background workers),
+  # objects that include this DSL may be created and destroyed frequently.
+  # Without WeakRef, the registry would hold strong references to these
+  # objects, preventing garbage collection and causing memory leaks.
+  #
+  # Example scenario: A Rails controller that includes BreakerMachines::DSL
+  # is instantiated for each request. Without WeakRef, every controller
+  # instance would be kept in memory forever.
+  module DSL
+    extend ActiveSupport::Concern
+
+    # Track instances for each class that includes DSL
+    # Using WeakRef to allow garbage collection
+    @instance_registries = Concurrent::Map.new
+
+    class_methods do
+      # Get or create instance registry for this class
+      def instance_registry
+        # Access the module-level registry
+        registry = BreakerMachines::DSL.instance_variable_get(:@instance_registries)
+        registry.compute_if_absent(self) { Concurrent::Array.new }
+      end
+
+      # Clean up dead references in the registry
+      def cleanup_instance_registry
+        registry = instance_registry
+        # Concurrent::Array supports delete_if
+        registry.delete_if do |weak_ref|
+          weak_ref.__getobj__
+          false
+        rescue WeakRef::RefError
+          true
+        end
+      end
+
+      def circuit(name, &block)
+        @circuits ||= {}
+
+        if block_given?
+          builder = CircuitBuilder.new
+          builder.instance_eval(&block)
+          @circuits[name] = builder.config
+        end
+
+        @circuits[name]
+      end
+
+      def circuits
+        # Start with parent circuits if available
+        base_circuits = if superclass.respond_to?(:circuits)
+                          superclass.circuits.deep_dup
+                        else
+                          {}
+                        end
+
+        # Merge with our own circuits
+        if @circuits
+          base_circuits.merge(@circuits)
+        else
+          base_circuits
+        end
+      end
+
+      # Get circuit definitions without sensitive data
+      def circuit_definitions
+        circuits.transform_values { |config| config.except(:owner, :storage, :metrics) }
+      end
+
+      # Reset all circuits for all instances of this class
+      def reset_all_circuits
+        cleanup_instance_registry # Clean up dead refs first
+
+        instance_registry.each do |weak_ref|
+          instance = weak_ref.__getobj__
+          circuit_instances = instance.instance_variable_get(:@circuit_instances)
+          circuit_instances&.each_value(&:reset)
+        rescue WeakRef::RefError
+          # Instance was garbage collected, skip it
+        end
+      end
+
+      # Get aggregated stats for all circuits of this class
+      def circuit_stats
+        stats = Hash.new { |h, k| h[k] = { total: 0, by_state: {} } }
+        cleanup_instance_registry # Clean up dead refs first
+
+        instance_registry.each do |weak_ref|
+          instance = weak_ref.__getobj__
+          circuit_instances = instance.instance_variable_get(:@circuit_instances)
+          next unless circuit_instances
+
+          circuit_instances.each do |name, circuit|
+            stats[name][:total] += 1
+            state = circuit.status_name
+            stats[name][:by_state][state] ||= 0
+            stats[name][:by_state][state] += 1
+          end
+        rescue WeakRef::RefError
+          # Instance was garbage collected, skip it
+        end
+
+        stats
+      end
+    end
+
+    # Use included callback to add instance tracking
+    def self.included(base)
+      super
+
+      # Hook into new to register instances
+      base.singleton_class.prepend(Module.new do
+        def new(...)
+          instance = super
+          instance_registry << WeakRef.new(instance)
+          instance
+        end
+      end)
+    end
+
+    def circuit(name)
+      self.class.circuits[name] ||= {}
+      @circuit_instances ||= {}
+      @circuit_instances[name] ||= Circuit.new(name, self.class.circuits[name].merge(owner: self))
+    end
+
+    # Get all circuit instances for this object
+    def circuit_instances
+      @circuit_instances || {}
+    end
+
+    # Get summary of all circuits for this instance
+    def circuits_summary
+      circuit_instances.transform_values(&:summary)
+    end
+
+    # Get detailed information for all circuits
+    def circuits_report
+      circuit_instances.transform_values(&:to_h)
+    end
+
+    # Reset all circuits for this instance
+    def reset_all_circuits
+      circuit_instances.each_value(&:reset)
+    end
+
+    # DSL builder for configuring circuit breakers with a fluent interface
+    class CircuitBuilder
+      attr_reader :config
+
+      def initialize
+        @config = {
+          failure_threshold: 5,
+          failure_window: 60,
+          success_threshold: 1,
+          timeout: nil,
+          reset_timeout: 60,
+          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, within: 60, successes: nil)
+        @config[:failure_threshold] = failures if failures
+        @config[:failure_window] = within.to_i
+        @config[:success_threshold] = successes if successes
+      end
+
+      def reset_after(duration, jitter: nil)
+        @config[:reset_timeout] = duration.to_i
+        @config[:reset_timeout_jitter] = jitter if jitter
+      end
+
+      def timeout(duration)
+        @config[:timeout] = duration.to_i
+      end
+
+      def half_open_requests(count)
+        @config[:half_open_calls] = count
+      end
+
+      def storage(backend, **)
+        @config[:storage] = case backend
+                            when :memory
+                              Storage::Memory.new(**)
+                            when :bucket_memory
+                              Storage::BucketMemory.new(**)
+                            when :redis
+                              Storage::Redis.new(**)
+                            when Class
+                              backend.new(**)
+                            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
+
+      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)
+        @config[:fiber_safe] = enabled
+      end
+
+      # Advanced features
+      def backends(list)
+        @config[:backends] = list
+      end
+
+      def parallel_calls(count, timeout: nil)
+        @config[:parallel_calls] = count
+        @config[:parallel_timeout] = timeout
+      end
+    end
+  end
+end

data/lib/breaker_machines/errors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Error < StandardError; end
+
+  # Raised when attempting to use a circuit that is in the open state
+  class CircuitOpenError < Error
+    attr_reader :circuit_name, :opened_at
+
+    def initialize(circuit_name, opened_at = nil)
+      @circuit_name = circuit_name
+      @opened_at = opened_at
+      super("Circuit '#{circuit_name}' is open")
+    end
+  end
+
+  # Raised when a circuit-protected call exceeds the configured timeout
+  class CircuitTimeoutError < Error
+    attr_reader :circuit_name, :timeout
+
+    def initialize(circuit_name, timeout)
+      @circuit_name = circuit_name
+      @timeout = timeout
+      super("Circuit '#{circuit_name}' timed out after #{timeout}s")
+    end
+  end
+
+  class ConfigurationError < Error; end
+  class StorageError < Error; end
+end