breaker_machines 0.1.0

data/lib/breaker_machines/registry.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require 'weakref'
+
+module BreakerMachines
+  # Global registry for tracking all circuit breaker instances
+  class Registry
+    include Singleton
+
+    def initialize
+      @circuits = Concurrent::Map.new
+      @mutex = Mutex.new
+      @registration_count = 0
+      @cleanup_interval = 100 # Clean up every N registrations
+    end
+
+    # Register a circuit instance
+    def register(circuit)
+      @mutex.synchronize do
+        # Use circuit object as key - Concurrent::Map handles object identity correctly
+        @circuits[circuit] = WeakRef.new(circuit)
+
+        # Periodic cleanup
+        @registration_count += 1
+        if @registration_count >= @cleanup_interval
+          cleanup_dead_references_unsafe
+          @registration_count = 0
+        end
+      end
+    end
+
+    # Unregister a circuit instance
+    def unregister(circuit)
+      @mutex.synchronize do
+        @circuits.delete(circuit)
+      end
+    end
+
+    # Get all active circuits
+    def all_circuits
+      @mutex.synchronize do
+        @circuits.values.map do |weak_ref|
+          weak_ref.__getobj__
+        rescue WeakRef::RefError
+          nil
+        end.compact
+      end
+    end
+
+    # Find circuits by name
+    def find_by_name(name)
+      all_circuits.select { |circuit| circuit.name == name }
+    end
+
+    # Get summary statistics
+    def stats_summary
+      circuits = all_circuits
+      {
+        total: circuits.size,
+        by_state: circuits.group_by(&:status_name).transform_values(&:count),
+        by_name: circuits.group_by(&:name).transform_values(&:count)
+      }
+    end
+
+    # Get detailed information for all circuits
+    def detailed_report
+      all_circuits.map(&:to_h)
+    end
+
+    # Clear all circuits (useful for testing)
+    def clear
+      @mutex.synchronize do
+        @circuits.clear
+      end
+    end
+
+    # Clean up dead references (thread-safe)
+    def cleanup_dead_references
+      @mutex.synchronize do
+        cleanup_dead_references_unsafe
+      end
+    end
+
+    private
+
+    # Clean up dead references (must be called within mutex)
+    def cleanup_dead_references_unsafe
+      dead_ids = []
+      @circuits.each_pair do |id, weak_ref|
+        weak_ref.__getobj__
+      rescue WeakRef::RefError
+        dead_ids << id
+      end
+
+      dead_ids.each { |id| @circuits.delete(id) }
+    end
+  end
+end

data/lib/breaker_machines/storage/base.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module Storage
+    # Abstract base class for storage backends
+    class Base
+      def initialize(**options)
+        @options = options
+      end
+
+      # Status management
+      def get_status(circuit_name)
+        raise NotImplementedError
+      end
+
+      def set_status(circuit_name, status, opened_at = nil)
+        raise NotImplementedError
+      end
+
+      # Metrics tracking
+      def record_success(circuit_name, duration)
+        raise NotImplementedError
+      end
+
+      def record_failure(circuit_name, duration)
+        raise NotImplementedError
+      end
+
+      def success_count(circuit_name, window_seconds)
+        raise NotImplementedError
+      end
+
+      def failure_count(circuit_name, window_seconds)
+        raise NotImplementedError
+      end
+
+      # Cleanup
+      def clear(circuit_name)
+        raise NotImplementedError
+      end
+
+      def clear_all
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/breaker_machines/storage/bucket_memory.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'concurrent/map'
+require 'concurrent/array'
+
+module BreakerMachines
+  module Storage
+    # Efficient bucket-based memory storage implementation
+    # Uses fixed-size circular buffers for constant-time event counting
+    class BucketMemory < Base
+      BUCKET_SIZE = 1 # 1 second per bucket
+
+      def initialize(**options)
+        super
+        @circuits = Concurrent::Map.new
+        @circuit_buckets = Concurrent::Map.new
+        @event_logs = Concurrent::Map.new
+        @bucket_count = options[:bucket_count] || 300 # Default 5 minutes
+        @max_events = options[:max_events] || 100
+      end
+
+      def get_status(circuit_name)
+        circuit_data = @circuits[circuit_name]
+        return nil unless circuit_data
+
+        {
+          status: circuit_data[:status],
+          opened_at: circuit_data[:opened_at]
+        }
+      end
+
+      def set_status(circuit_name, status, opened_at = nil)
+        @circuits[circuit_name] = {
+          status: status,
+          opened_at: opened_at,
+          updated_at: monotonic_time
+        }
+      end
+
+      def record_success(circuit_name, duration)
+        record_event(circuit_name, :success, duration)
+      end
+
+      def record_failure(circuit_name, duration)
+        record_event(circuit_name, :failure, duration)
+      end
+
+      def success_count(circuit_name, window_seconds)
+        count_events(circuit_name, :success, window_seconds)
+      end
+
+      def failure_count(circuit_name, window_seconds)
+        count_events(circuit_name, :failure, window_seconds)
+      end
+
+      def clear(circuit_name)
+        @circuits.delete(circuit_name)
+        @circuit_buckets.delete(circuit_name)
+        @event_logs.delete(circuit_name)
+      end
+
+      def clear_all
+        @circuits.clear
+        @circuit_buckets.clear
+        @event_logs.clear
+      end
+
+      def record_event_with_details(circuit_name, type, duration, error: nil, new_state: nil)
+        events = @event_logs.compute_if_absent(circuit_name) { Concurrent::Array.new }
+
+        event = {
+          type: type,
+          timestamp: monotonic_time,
+          duration_ms: (duration * 1000).round(2)
+        }
+
+        event[:error_class] = error.class.name if error
+        event[:error_message] = error.message if error
+        event[:new_state] = new_state if new_state
+
+        events << event
+
+        # Keep only the most recent events
+        events.shift while events.size > @max_events
+      end
+
+      def event_log(circuit_name, limit)
+        events = @event_logs[circuit_name]
+        return [] unless events
+
+        events.last(limit).map(&:dup)
+      end
+
+      private
+
+      def record_event(circuit_name, type, _duration)
+        buckets = @circuit_buckets.compute_if_absent(circuit_name) do
+          {
+            successes: Concurrent::Array.new(@bucket_count) { Concurrent::AtomicFixnum.new(0) },
+            failures: Concurrent::Array.new(@bucket_count) { Concurrent::AtomicFixnum.new(0) },
+            last_bucket_time: Concurrent::AtomicReference.new(current_bucket_time)
+          }
+        end
+
+        current_time = current_bucket_time
+        rotate_buckets_if_needed(buckets, current_time)
+
+        bucket_index = current_time % @bucket_count
+        counter_array = type == :success ? buckets[:successes] : buckets[:failures]
+        counter_array[bucket_index].increment
+      end
+
+      def count_events(circuit_name, type, window_seconds)
+        buckets = @circuit_buckets[circuit_name]
+        return 0 unless buckets
+
+        current_time = current_bucket_time
+        rotate_buckets_if_needed(buckets, current_time)
+
+        # Calculate how many buckets to count
+        buckets_to_count = [window_seconds / BUCKET_SIZE, @bucket_count].min.to_i
+
+        counter_array = type == :success ? buckets[:successes] : buckets[:failures]
+        total = 0
+
+        buckets_to_count.times do |i|
+          bucket_index = (current_time - i) % @bucket_count
+          total += counter_array[bucket_index].value
+        end
+
+        total
+      end
+
+      def rotate_buckets_if_needed(buckets, current_time)
+        last_time = buckets[:last_bucket_time].value
+
+        return if current_time == last_time
+
+        # Only one thread should rotate buckets
+        return unless buckets[:last_bucket_time].compare_and_set(last_time, current_time)
+
+        # Clear buckets that are now outdated
+        time_diff = current_time - last_time
+        buckets_to_clear = [time_diff, @bucket_count].min
+
+        buckets_to_clear.times do |i|
+          # Clear the bucket that will be reused
+          bucket_index = (last_time + i + 1) % @bucket_count
+          buckets[:successes][bucket_index].value = 0
+          buckets[:failures][bucket_index].value = 0
+        end
+      end
+
+      def current_bucket_time
+        (monotonic_time / BUCKET_SIZE).to_i
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/breaker_machines/storage/memory.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'concurrent/map'
+require 'concurrent/array'
+
+module BreakerMachines
+  module Storage
+    # High-performance in-memory storage backend with thread-safe operations
+    class Memory < Base
+      def initialize(**options)
+        super
+        @circuits = Concurrent::Map.new
+        @events = Concurrent::Map.new
+        @event_logs = Concurrent::Map.new
+        @max_events = options[:max_events] || 100
+      end
+
+      def get_status(circuit_name)
+        circuit_data = @circuits[circuit_name]
+        return nil unless circuit_data
+
+        {
+          status: circuit_data[:status],
+          opened_at: circuit_data[:opened_at]
+        }
+      end
+
+      def set_status(circuit_name, status, opened_at = nil)
+        @circuits[circuit_name] = {
+          status: status,
+          opened_at: opened_at,
+          updated_at: monotonic_time
+        }
+      end
+
+      def record_success(circuit_name, duration)
+        record_event(circuit_name, :success, duration)
+      end
+
+      def record_failure(circuit_name, duration)
+        record_event(circuit_name, :failure, duration)
+      end
+
+      def success_count(circuit_name, window_seconds)
+        count_events(circuit_name, :success, window_seconds)
+      end
+
+      def failure_count(circuit_name, window_seconds)
+        count_events(circuit_name, :failure, window_seconds)
+      end
+
+      def clear(circuit_name)
+        @circuits.delete(circuit_name)
+        @events.delete(circuit_name)
+        @event_logs.delete(circuit_name)
+      end
+
+      def clear_all
+        @circuits.clear
+        @events.clear
+        @event_logs.clear
+      end
+
+      def record_event_with_details(circuit_name, type, duration, error: nil, new_state: nil)
+        events = @event_logs.compute_if_absent(circuit_name) { Concurrent::Array.new }
+
+        event = {
+          type: type,
+          timestamp: monotonic_time,
+          duration_ms: (duration * 1000).round(2)
+        }
+
+        event[:error_class] = error.class.name if error
+        event[:error_message] = error.message if error
+        event[:new_state] = new_state if new_state
+
+        events << event
+
+        # Keep only the most recent events
+        events.shift while events.size > @max_events
+      end
+
+      def event_log(circuit_name, limit)
+        events = @event_logs[circuit_name]
+        return [] unless events
+
+        events.last(limit).map(&:dup)
+      end
+
+      private
+
+      def record_event(circuit_name, type, duration)
+        # Initialize if needed
+        @events.compute_if_absent(circuit_name) { Concurrent::Array.new }
+
+        # Get the array and add event
+        events = @events[circuit_name]
+        current_time = monotonic_time
+
+        # Add new event
+        events << {
+          type: type,
+          duration: duration,
+          timestamp: current_time
+        }
+
+        # Clean old events periodically (every 100 events)
+        return unless events.size > 100
+
+        cutoff_time = current_time - 300 # Keep 5 minutes of history
+        events.delete_if { |e| e[:timestamp] < cutoff_time }
+      end
+
+      def count_events(circuit_name, type, window_seconds)
+        events = @events[circuit_name]
+        return 0 unless events
+
+        cutoff_time = monotonic_time - window_seconds
+        events.count { |e| e[:type] == type && e[:timestamp] >= cutoff_time }
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/breaker_machines/storage/null.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  module Storage
+    # A no-op storage backend for minimal overhead
+    # Use this when you don't need event logging or metrics
+    class Null < Base
+      def record_success(_circuit_name, _duration = nil)
+        # No-op
+      end
+
+      def record_failure(_circuit_name, _duration = nil)
+        # No-op
+      end
+
+      def success_count(_circuit_name, _window = nil)
+        0
+      end
+
+      def failure_count(_circuit_name, _window = nil)
+        0
+      end
+
+      def get_status(_circuit_name)
+        nil
+      end
+
+      def set_status(_circuit_name, _status, _opened_at = nil)
+        # No-op
+      end
+
+      def clear(_circuit_name)
+        # No-op
+      end
+
+      def event_log(_circuit_name, _limit = 20)
+        []
+      end
+
+      def record_event_with_details(_circuit_name, _event_type, _duration, _metadata = {})
+        # No-op
+      end
+    end
+  end
+end

data/lib/breaker_machines/storage.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  # Storage backends for persisting circuit state and metrics
+  module Storage
+    # Storage module for circuit breaker state persistence
+  end
+end

data/lib/breaker_machines/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  VERSION = '0.1.0'
+end

data/lib/breaker_machines.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+require 'active_support'
+require 'active_support/core_ext'
+require_relative 'breaker_machines/errors'
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect('dsl' => 'DSL')
+loader.ignore("#{__dir__}/breaker_machines/errors.rb")
+loader.ignore("#{__dir__}/breaker_machines/console.rb")
+loader.setup
+
+# BreakerMachines provides a thread-safe implementation of the Circuit Breaker pattern
+# for Ruby applications, helping to prevent cascading failures in distributed systems.
+module BreakerMachines
+  class << self
+    def loader
+      loader
+    end
+  end
+
+  # Global configuration
+  include ActiveSupport::Configurable
+
+  config_accessor :default_storage, default: :bucket_memory
+  config_accessor :default_timeout, default: nil
+  config_accessor :default_reset_timeout, default: 60
+  config_accessor :default_failure_threshold, default: 5
+  config_accessor :log_events, default: true
+  config_accessor :fiber_safe, default: false
+
+  class << self
+    def configure
+      yield config
+    end
+
+    def setup_notifications
+      return unless config.log_events
+
+      ActiveSupport::Notifications.subscribe(/^breaker_machines\./) do |name, _start, _finish, _id, payload|
+        event_type = name.split('.').last
+        circuit_name = payload[:circuit]
+
+        case event_type
+        when 'opened'
+          logger&.warn "[BreakerMachines] Circuit '#{circuit_name}' opened"
+        when 'closed'
+          logger&.info "[BreakerMachines] Circuit '#{circuit_name}' closed"
+        when 'half_opened'
+          logger&.info "[BreakerMachines] Circuit '#{circuit_name}' half-opened"
+        end
+      end
+    end
+
+    def logger
+      @logger ||= ActiveSupport::Logger.new($stdout)
+    end
+
+    attr_writer :logger
+
+    def instrument(event, payload = {})
+      return unless config.log_events
+
+      ActiveSupport::Notifications.instrument("breaker_machines.#{event}", payload)
+    end
+
+    # Launch the interactive console
+    def console
+      require_relative 'breaker_machines/console'
+      Console.start
+    end
+
+    # Get the global registry
+    def registry
+      Registry.instance
+    end
+  end
+
+  # Set up notifications on first use
+  setup_notifications if config.log_events
+end

data/sig/README.md

@@ -0,0 +1,74 @@
+# BreakerMachines RBS Type Signatures
+
+This directory contains RBS (Ruby type signatures) for the BreakerMachines gem.
+
+## Structure
+
+- `breaker_machines.rbs` - Main module and configuration
+- `breaker_machines/` - Type signatures for all classes and modules
+  - `circuit.rbs` - Circuit class and its modules
+  - `errors.rbs` - Error classes
+  - `storage.rbs` - Storage backends
+  - `dsl.rbs` - DSL module for including in classes
+  - `registry.rbs` - Global circuit registry
+  - `console.rbs` - Interactive console
+  - `types.rbs` - Common type aliases
+  - `interfaces.rbs` - Interface definitions
+
+## Usage
+
+To use these type signatures in your project:
+
+1. Add to your `Steepfile`:
+   ```ruby
+   target :app do
+     signature "sig"
+     check "lib"
+     
+     library "breaker_machines"
+   end
+   ```
+
+2. Or with RBS directly:
+   ```bash
+   rbs validate
+   ```
+
+## Type Checking Examples
+
+### Basic Circuit Usage
+```ruby
+circuit = BreakerMachines::Circuit.new("api", 
+  failure_threshold: 5,
+  reset_timeout: 30
+)
+
+result = circuit.call { api.fetch_data }
+```
+
+### DSL Usage
+```ruby
+class MyService
+  include BreakerMachines::DSL
+  
+  circuit :database do
+    threshold failures: 10, within: 60
+    reset_after 120
+    fallback { [] }
+  end
+end
+```
+
+## Key Types
+
+- `circuit_state` - `:open | :closed | :half_open`
+- `storage_backend` - `:memory | :bucket_memory | :null | :redis`
+- `circuit_options` - Configuration hash for circuits
+- `event_record` - Structure for logged events
+
+## Interfaces
+
+The type signatures define several interfaces:
+- `_StorageBackend` - For custom storage implementations
+- `_MetricsRecorder` - For custom metrics recording
+- `_CircuitLike` - For circuit-compatible objects

data/sig/all.rbs

@@ -0,0 +1,25 @@
+# Main entry point for BreakerMachines RBS types
+#
+# This file provides a complete type definition for the BreakerMachines gem,
+# a Ruby implementation of the Circuit Breaker pattern.
+#
+# Usage:
+#   class MyService
+#     include BreakerMachines::DSL
+#
+#     circuit :api_call do
+#       threshold failures: 5, within: 60
+#       reset_after 30
+#       fallback { |error| { error: "Service unavailable" } }
+#     end
+#
+#     def fetch_data
+#       circuit(:api_call).call do
+#         # Your API call here
+#       end
+#     end
+#   end
+
+# Import all type definitions
+use BreakerMachines::*
+use BreakerMachines::Storage::*