breaker_machines 0.9.2-arm64-darwin

data/lib/breaker_machines.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+require 'active_support'
+require 'active_support/core_ext'
+require 'state_machines'
+require_relative 'breaker_machines/errors'
+require_relative 'breaker_machines/types'
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect('dsl' => 'DSL')
+loader.ignore("#{__dir__}/breaker_machines/errors.rb")
+loader.ignore("#{__dir__}/breaker_machines/types.rb")
+loader.ignore("#{__dir__}/breaker_machines/console.rb")
+loader.ignore("#{__dir__}/breaker_machines/async_support.rb")
+loader.ignore("#{__dir__}/breaker_machines/hedged_async_support.rb")
+loader.ignore("#{__dir__}/breaker_machines/circuit/async_state_management.rb")
+loader.ignore("#{__dir__}/breaker_machines/native_speedup.rb")
+loader.ignore("#{__dir__}/breaker_machines/native_extension.rb")
+loader.ignore("#{__dir__}/breaker_machines/storage/native.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
+  # Global configuration class for BreakerMachines
+  class Configuration
+    attr_accessor :default_storage,
+                  :default_timeout,
+                  :default_reset_timeout,
+                  :default_failure_threshold,
+                  :log_events,
+                  :fiber_safe
+
+    def initialize
+      @default_storage = :bucket_memory
+      @default_timeout = nil
+      @default_reset_timeout = 60.seconds
+      @default_failure_threshold = 5
+      @log_events = true
+      @fiber_safe = false
+    end
+  end
+
+  class << self
+    def loader
+      loader
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Delegate config attributes to config object for backward compatibility
+    def default_storage
+      config.default_storage
+    end
+
+    def default_storage=(value)
+      config.default_storage = value
+    end
+
+    def default_timeout
+      config.default_timeout
+    end
+
+    def default_timeout=(value)
+      config.default_timeout = value
+    end
+
+    def default_reset_timeout
+      config.default_reset_timeout
+    end
+
+    def default_reset_timeout=(value)
+      config.default_reset_timeout = value
+    end
+
+    def default_failure_threshold
+      config.default_failure_threshold
+    end
+
+    def default_failure_threshold=(value)
+      config.default_failure_threshold = value
+    end
+
+    def log_events
+      config.log_events
+    end
+
+    def log_events=(value)
+      config.log_events = value
+    end
+
+    def fiber_safe
+      config.fiber_safe
+    end
+
+    def fiber_safe=(value)
+      config.fiber_safe = value
+    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
+
+    # Centralized logging helper
+    # @param level [Symbol] log level (:debug, :info, :warn, :error)
+    # @param message [String] message to log
+    def log(level, message)
+      return unless config.log_events && logger
+
+      logger.public_send(level, "[BreakerMachines] #{message}")
+    end
+
+    def instrument(event, payload = {})
+      return unless config.log_events
+
+      ActiveSupport::Notifications.instrument("breaker_machines.#{event}", payload)
+    end
+
+    # Check if native extension is available
+    # @return [Boolean] true if native extension loaded successfully
+    def native_available?
+      @native_available || false
+    end
+
+    # Launch the interactive console
+    def console
+      require_relative 'breaker_machines/console'
+      Console.start
+    end
+
+    # Get the global registry
+    def registry
+      Registry.instance
+    end
+
+    # Register a circuit with the global registry
+    def register(circuit)
+      registry.register(circuit)
+    end
+
+    # Reset the registry and configurations (useful for testing)
+    def reset!
+      registry.clear
+      config.default_storage = :bucket_memory
+      config.default_timeout = nil
+      config.default_reset_timeout = 60.seconds
+      config.default_failure_threshold = 5
+      config.log_events = true
+      config.fiber_safe = false
+    end
+
+    # Returns the current monotonic time in seconds.
+    # Monotonic time is guaranteed to always increase and is not affected
+    # by system clock adjustments, making it ideal for measuring durations.
+    #
+    # @return [Float] current monotonic time in seconds
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+
+  # Set up notifications on first use
+  setup_notifications if config.log_events
+end
+
+# Load optional native speedup after core is loaded
+# Automatically loads if available, gracefully falls back to pure Ruby if not
+begin
+  require_relative 'breaker_machines/native_speedup'
+rescue LoadError
+  # Native extension not available, using pure Ruby backend
+  # This is expected on JRuby or when Cargo is not available
+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::*

data/sig/breaker_machines/circuit.rbs

@@ -0,0 +1,154 @@
+module BreakerMachines
+  class Circuit
+    include StateManagement
+    include Configuration
+    include Execution
+    include Introspection
+    include Callbacks
+
+    # Instance variables from Configuration module
+    @name: String
+    @config: Hash[Symbol, untyped]
+    @storage: _StorageBackend?
+    @metrics: _MetricsRecorder?
+    @opened_at: Concurrent::AtomicReference[Float?]
+    @half_open_attempts: Concurrent::AtomicFixnum
+    @half_open_successes: Concurrent::AtomicFixnum
+    @mutex: Concurrent::ReentrantReadWriteLock
+    @last_failure_at: Concurrent::AtomicReference[Float?]
+    @last_error: Concurrent::AtomicReference[StandardError?]
+
+    # State machine status (from StateManagement)
+    attr_reader status: (:open | :closed | :half_open)
+  end
+
+  module StateManagement
+    interface _StateManagementState
+      def status: () -> (:open | :closed | :half_open)
+      def status=: (:open | :closed | :half_open value) -> void
+      def status_name: () -> (:open | :closed | :half_open)
+      def open?: () -> bool
+      def closed?: () -> bool
+      def half_open?: () -> bool
+      def trip: () -> bool
+      def attempt_recovery: () -> bool
+      def reset: () -> bool
+      def force_open: () -> bool
+      def force_close: () -> bool
+    end
+
+    def self.included: (singleton(Circuit) base) -> void
+
+    private
+
+    def on_circuit_open: () -> void
+    def on_circuit_close: () -> void
+    def on_circuit_half_open: () -> void
+    def restore_status_from_storage: () -> void
+    def reset_timeout_elapsed?: () -> bool
+    def monotonic_time: () -> Float
+  end
+
+  module Configuration
+    extend ActiveSupport::Concern
+
+    interface _ConfigurationMethods
+      def name: () -> String
+      def config: () -> Hash[Symbol, untyped]
+      def opened_at: () -> Concurrent::AtomicReference[Float?]
+    end
+
+    type storage_type = Storage::Base | Storage::Memory | Storage::BucketMemory | Storage::Null
+    type metrics_type = untyped
+    type callback_type = Proc | nil
+    type fallback_type = Proc | Array[Proc | untyped] | untyped
+
+    type circuit_config = {
+      failure_threshold: Integer,
+      failure_window: Integer,
+      success_threshold: Integer,
+      timeout: Integer?,
+      reset_timeout: Integer,
+      reset_timeout_jitter: Float,
+      half_open_calls: Integer,
+      storage: storage_type?,
+      metrics: metrics_type?,
+      fallback: fallback_type?,
+      on_open: callback_type,
+      on_close: callback_type,
+      on_half_open: callback_type,
+      on_reject: callback_type,
+      exceptions: Array[Class],
+      owner: untyped
+    }
+
+    def initialize: (String name, ?circuit_config options) -> void
+
+    private
+
+    def default_config: () -> circuit_config
+    def create_default_storage: () -> storage_type
+  end
+
+  module Execution
+    def call: [T] () { () -> T } -> untyped
+    def wrap: [T] () { () -> T } -> untyped
+
+    private
+
+    def handle_open_status: () { () -> untyped } -> untyped
+    def handle_half_open_status: () { () -> untyped } -> untyped
+    def handle_closed_status: () { () -> untyped } -> untyped
+    def execute_call: () { () -> untyped } -> untyped
+    def reject_call: () -> untyped
+    def handle_success: () -> void
+    def handle_failure: () -> void
+    def failure_threshold_exceeded?: () -> bool
+    def success_threshold_reached?: () -> bool
+    def record_success: (Float duration) -> void
+    def record_failure: (Float duration, ?StandardError? error) -> void
+  end
+
+  module Introspection
+    type stats_hash = {
+      state: (:open | :closed | :half_open),
+      failure_count: Integer,
+      success_count: Integer,
+      last_failure_at: Float?,
+      opened_at: Float?,
+      half_open_attempts: Integer,
+      half_open_successes: Integer
+    }
+
+    type error_info = {
+      class: String,
+      message: String,
+      occurred_at: Float
+    }
+
+    type circuit_hash = {
+      name: String,
+      state: (:open | :closed | :half_open),
+      stats: stats_hash,
+      config: Hash[Symbol, untyped],
+      event_log: Array[untyped],
+      last_error: error_info?
+    }
+
+    def stats: () -> stats_hash
+    def configuration: () -> Hash[Symbol, untyped]
+    def event_log: (?limit: Integer) -> Array[untyped]?
+    def last_error: () -> StandardError?
+    def to_h: () -> circuit_hash
+    def summary: () -> String
+    def last_error_info: () -> error_info?
+  end
+
+  module Callbacks
+    private
+
+    def invoke_callback: (Symbol callback_name) -> void
+    def invoke_fallback: (StandardError error) -> untyped
+    def invoke_single_fallback: (Proc | untyped fallback, StandardError error) -> untyped
+  end
+end

data/sig/breaker_machines/console.rbs

@@ -0,0 +1,32 @@
+module BreakerMachines
+  class Console
+    @running: bool
+
+    def self.start: () -> void
+
+    def initialize: () -> void
+    def run: () -> void
+
+    private
+
+    def print_header: () -> void
+    def print_help: () -> void
+    def print_prompt: () -> void
+    def process_command: (String command) -> void
+
+    # Command methods
+    def list_circuits: () -> void
+    def show_stats: () -> void
+    def show_circuit: (String? name) -> void
+    def show_events: (String? name, Integer limit) -> void
+    def reset_circuit: (String? name) -> void
+    def force_open_circuit: (String? name) -> void
+    def force_close_circuit: (String? name) -> void
+    def generate_report: () -> void
+    def cleanup_registry: () -> void
+
+    # Utility methods
+    def colorize_state: (Symbol state) -> String
+    def colorize_event_type: (Symbol type) -> String
+  end
+end

data/sig/breaker_machines/dsl.rbs

@@ -0,0 +1,50 @@
+module BreakerMachines
+  module DSL
+    extend ActiveSupport::Concern
+
+    @instance_registries: Concurrent::Map[Class, Concurrent::Array[WeakRef[untyped]]]
+
+    module ClassMethods
+      @circuits: Hash[Symbol, Hash[Symbol, untyped]]
+
+      def instance_registry: () -> Concurrent::Array[WeakRef[untyped]]
+      def cleanup_instance_registry: () -> void
+      def circuit: (Symbol name) ?{ (CircuitBuilder) -> void } -> Hash[Symbol, untyped]
+      def circuits: () -> Hash[Symbol, Hash[Symbol, untyped]]
+      def circuit_definitions: () -> Hash[Symbol, Hash[Symbol, untyped]]
+      def reset_all_circuits: () -> void
+      def circuit_stats: () -> Hash[Symbol, { total: Integer, by_state: Hash[Symbol, Integer] }]
+    end
+
+    def circuit: (Symbol name) -> Circuit
+    def circuit_instances: () -> Hash[Symbol, Circuit]
+    def circuits_summary: () -> Hash[Symbol, String]
+    def circuits_report: () -> Hash[Symbol, untyped]
+    def reset_all_circuits: () -> void
+
+    class CircuitBuilder
+      attr_reader config: Hash[Symbol, untyped]
+
+      def initialize: () -> void
+
+      # Configuration methods
+      def threshold: (?failures: Integer?, ?within: Integer, ?successes: Integer?) -> void
+      def reset_after: (Integer duration, ?jitter: Float?) -> void
+      def timeout: (Integer duration) -> void
+      def half_open_requests: (Integer count) -> void
+      def storage: ((:memory | :bucket_memory | :redis | Class | Storage::Base) backend, **untyped) -> void
+      def metrics: (?untyped recorder) ?{ () -> void } -> void
+      def fallback: (?untyped value) ?{ (StandardError) -> untyped } -> void
+      def on_open: () { () -> void } -> void
+      def on_close: () { () -> void } -> void
+      def on_half_open: () { () -> void } -> void
+      def on_reject: () { () -> void } -> void
+      def notify: (Symbol service, ?String? url, ?events: Array[Symbol], **untyped options) -> void
+      def handle: (*Class exceptions) -> void
+
+      # Advanced features
+      def backends: (Array[untyped] list) -> void
+      def parallel_calls: (Integer count, ?timeout: Integer?) -> void
+    end
+  end
+end

data/sig/breaker_machines/errors.rbs

@@ -0,0 +1,24 @@
+module BreakerMachines
+  class Error < StandardError
+  end
+
+  class CircuitOpenError < Error
+    attr_reader circuit_name: String
+    attr_reader opened_at: Float?
+
+    def initialize: (String circuit_name, ?Float? opened_at) -> void
+  end
+
+  class CircuitTimeoutError < Error
+    attr_reader circuit_name: String
+    attr_reader timeout: Numeric
+
+    def initialize: (String circuit_name, Numeric timeout) -> void
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class StorageError < Error
+  end
+end

data/sig/breaker_machines/interfaces.rbs

@@ -0,0 +1,46 @@
+module BreakerMachines
+  # Interface for objects that can record metrics
+  interface _MetricsRecorder
+    def record_success: (String circuit_name, Float duration) -> void
+    def record_failure: (String circuit_name, Float duration) -> void
+    def record_rejection: (String circuit_name) -> void
+  end
+
+  # Interface for storage backends
+  interface _StorageBackend
+    def get_status: (String circuit_name) -> status_record?
+    def set_status: (String circuit_name, circuit_state status, ?Float? opened_at) -> void
+    def record_success: (String circuit_name, Float duration) -> void
+    def record_failure: (String circuit_name, Float duration) -> void
+    def success_count: (String circuit_name, Integer window_seconds) -> Integer
+    def failure_count: (String circuit_name, Integer window_seconds) -> Integer
+    def clear: (String circuit_name) -> void
+    def clear_all: () -> void
+  end
+
+  # Interface for advanced storage backends with event logging
+  interface _AdvancedStorageBackend
+    def record_success: (String circuit_name, ?Float? duration) -> void
+    def record_failure: (String circuit_name, ?Float? duration) -> void
+    def success_count: (String circuit_name, ?Integer? window) -> Integer
+    def failure_count: (String circuit_name, ?Integer? window) -> Integer
+    def get_status: (String circuit_name) -> Hash[Symbol, untyped]?
+    def set_status: (String circuit_name, circuit_state status, ?Float? opened_at) -> void
+    def clear: (String circuit_name) -> void
+    def record_event_with_details: (String circuit_name, event_type event_type, Float duration, ?Hash[Symbol, untyped] details) -> void
+    def event_log: (String circuit_name, ?Integer limit) -> Array[event_record]
+  end
+
+  # Interface for circuit-like objects
+  interface _CircuitLike
+    def name: () -> String
+    def call: () { () -> untyped } -> untyped
+    def wrap: () { () -> untyped } -> untyped
+    def status_name: () -> circuit_state
+    def open?: () -> bool
+    def closed?: () -> bool
+    def half_open?: () -> bool
+    def reset: () -> bool
+    def stats: () -> Hash[Symbol, untyped]
+  end
+end

data/sig/breaker_machines/registry.rbs

@@ -0,0 +1,30 @@
+module BreakerMachines
+  class Registry
+    include Singleton
+
+    @circuits: Concurrent::Map[Integer, WeakRef[Circuit]]
+    @mutex: Mutex
+    @registration_count: Integer
+    @cleanup_interval: Integer
+
+    def initialize: () -> void
+
+    # Circuit management
+    def register: (Circuit circuit) -> void
+    def unregister: (Circuit circuit) -> void
+    def all_circuits: () -> Array[Circuit]
+    def find_by_name: (Symbol name) -> Array[Circuit]
+
+    # Reporting
+    def stats_summary: () -> { total: Integer, by_state: Hash[Symbol, Integer], by_name: Hash[Symbol, Integer] }
+    def detailed_report: () -> Array[Hash[Symbol, untyped]]
+
+    # Maintenance
+    def clear: () -> void
+    def cleanup_dead_references: () -> void
+
+    private
+
+    def cleanup_dead_references_unsafe: () -> void
+  end
+end