breaker_machines 0.9.2-x86_64-linux-musl

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2b38e67c4a562dd8cfcbc6d1b5a2b637a151691a9150ca5bc11078e1e0b3ba85
+  data.tar.gz: 28216bd4d7d14e067689b4011a82202e7c433bc573139efa58513e592693927a
+SHA512:
+  metadata.gz: a7c1068a050e3318370c1efae59b52590e6ed25f5194773ebb123c7782e81ce6f0ee3887470dda382155e66a44ce41a59e71e0a6a4184afd798b87bcbfedcac4
+  data.tar.gz: b3c712f809759a54714590af8302fccb74f34659132b1c2a355088d0d35fda6826b451f7e7193e564acd84b842868e13960708c039b396611b682a1dd501b475

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Abdelkader Boudih
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,184 @@
+# BreakerMachines
+
+> The circuit breaker that went where no Ruby has gone before! ⭐
+
+A battle-tested Ruby implementation of the Circuit Breaker pattern, built on `state_machines` for reliable distributed systems protection.
+
+## Quick Start
+
+```bash
+gem 'breaker_machines'
+```
+
+```ruby
+class PaymentService
+  include BreakerMachines::DSL
+
+  circuit :stripe do
+    threshold failures: 3, within: 1.minute
+    reset_after 30.seconds
+    fallback { { error: "Payment queued for later" } }
+  end
+
+  def charge(amount)
+    circuit(:stripe).wrap do
+      Stripe::Charge.create(amount: amount)
+    end
+  end
+end
+```
+
+## A Message to the Resistance
+
+So AI took your job while you were waiting for Fireship to drop the next JavaScript framework?
+
+Welcome to April 2005—when Git was born, branches were just `master`, and nobody cared about your pronouns. This is the pattern your company's distributed systems desperately need, explained in a way that won't make you fall asleep and impulse-buy developer swag just to feel something.
+
+Still reading? Good. Because in space, nobody can hear you scream about microservices. It's all just patterns and pain.
+
+### The Pattern They Don't Want You to Know
+
+Built on the battle-tested `state_machines` gem, because I don't reinvent wheels here—I stop them from catching fire and burning down your entire infrastructure.
+
+## Features
+
+- **Thread-safe** circuit breaker implementation
+- **Fiber-safe mode** for async Ruby (Falcon, async gem)
+- **AsyncCircuit** class with mutex-protected state transitions
+- **Circuit Groups** for managing related circuits with dependencies
+- **Coordinated State Management** for dependency-aware transitions
+- **Cascading Circuit Breakers** for modeling system dependencies
+- **Hedged requests** for latency reduction
+- **Multiple backends** with automatic failover
+- **Bulkheading** to limit concurrent requests
+- **Percentage-based thresholds** with minimum call requirements
+- **Dynamic circuit breakers** with templates for runtime creation
+- **Pluggable storage** (Memory, Redis, Custom)
+- **Rich callbacks** and instrumentation
+- **ActiveSupport::Notifications** integration
+- **Cross-platform support** - Optimized for MRI, JRuby, and TruffleRuby
+
+## Documentation
+
+### Core Features
+- **Getting Started Guide** (docs/GETTING_STARTED.md) - Installation and basic usage
+- **Configuration Reference** (docs/CONFIGURATION.md) - All configuration options
+- **Advanced Patterns** (docs/ADVANCED_PATTERNS.md) - Complex scenarios and patterns
+
+### Advanced Features
+- **Circuit Groups** (docs/CIRCUIT_GROUPS.md) - Managing related circuits with dependencies
+- **Coordinated State Management** (docs/COORDINATED_STATE_MANAGEMENT.md) - Dependency-aware state transitions
+- **Cascading Circuit Breakers** (docs/CASCADING_CIRCUITS.md) - Modeling system dependencies
+
+### Async & Concurrency
+- **Async Mode** (docs/ASYNC.md) - Fiber-safe operations and AsyncCircuit
+- **Async Storage Examples** (docs/ASYNC_STORAGE_EXAMPLES.md) - Non-blocking storage backends
+
+### Storage & Persistence
+- **Persistence Options** (docs/PERSISTENCE.md) - Storage backends and distributed state
+
+### Testing
+- **Testing Guide** (docs/TESTING.md) - Testing strategies
+  - [RSpec Testing](docs/TESTING_RSPEC.md)
+  - [ActiveSupport Testing](docs/TESTING_ACTIVESUPPORT.md)
+
+### Integration & Monitoring
+- **Rails Integration** (docs/RAILS_INTEGRATION.md) - Rails-specific patterns
+- **Observability Guide** (docs/OBSERVABILITY.md) - Monitoring and metrics
+
+### Reference
+- **API Reference** (docs/API_REFERENCE.md) - Complete API documentation
+- **Horror Stories** (docs/HORROR_STORIES.md) - Real production failures and lessons learned
+
+## Why BreakerMachines?
+
+Built on the battle-tested `state_machines` gem, BreakerMachines provides production-ready circuit breaker functionality without reinventing the wheel. It's designed for modern Ruby applications with first-class support for fibers, async operations, and distributed systems.
+
+See [Why I Open Sourced This](docs/WHY_OPEN_SOURCE.md) for the full story.
+
+## Chapter 1: The Year is 2025 (Stardate 2025.186)
+
+The Resistance huddles in the server rooms, the last bastion against the cascade failures. Outside, the microservices burn. Redis Ship Com is down. PostgreSQL Life Support is flatlining.
+
+And somewhere in the darkness, a junior developer is about to write:
+
+```ruby
+def fetch_user_data
+  retry_count = 0
+  begin
+    @redis.get(user_id)
+  rescue => e
+    retry_count += 1
+    retry if retry_count < Float::INFINITY  # "It'll work eventually"
+  end
+end
+```
+
+"This," whispers the grizzled ops engineer, "is how civilizations fall."
+
+## The Hidden State Machine
+
+They built this on `state_machines` because sometimes, Resistance, you need a tank, not another JavaScript framework.
+
+See the [Circuit Breaker State Machine diagram](docs/DIAGRAMS.md#the-circuit-breaker-state-machine) for a visual representation of hope, despair, and the eternal cycle of production failures.
+
+## What You Think You're Doing vs Reality
+
+### You Think: "I'm implementing retry logic for resilience!"
+### Reality: You're DDOSing your own infrastructure
+
+See [The Retry Death Spiral diagram](docs/DIAGRAMS.md#the-retry-death-spiral) to understand how your well-intentioned retries become a self-inflicted distributed denial of service attack.
+
+## Advanced Features
+
+- **Hedged Requests** - Reduce latency with duplicate requests
+- **Multiple Backends** - Automatic failover across endpoints
+- **Percentage-Based Thresholds** - Open on error rates, not just counts
+- **Dynamic Circuit Breakers** - Runtime creation with templates
+- **Apocalypse-Resistant Storage** - Cascading fallbacks when Redis dies
+- **Custom Storage Backends** - SysV semaphores, distributed locks, etc.
+
+See [Advanced Patterns](docs/ADVANCED_PATTERNS.md) for detailed examples and implementation guides.
+
+## A Word from the RMNS Atlas Monkey
+
+*The Universal Commentary Engine crackles to life:*
+
+"In space, nobody can hear your pronouns. But they can hear your services failing.
+
+The universe doesn't care about your bootcamp certificate or your Medium articles about 'Why I Switched to Rust.' It cares about one thing:
+
+Does your system stay up when Redis has a bad day?
+
+If not, welcome to the Resistance. We have circuit breakers.
+
+Remember: The pattern isn't about preventing failures—it's about failing fast, failing smart, and living to deploy another day.
+
+As I always say when contemplating the void: 'It's better to break a circuit than to break production.'"
+
+*— Universal Commentary Engine, Log Entry 42*
+
+## Contributing to the Resistance
+
+1. Fork it (like it's 2005)
+2. Create your feature branch (`git checkout -b feature/save-the-fleet`)
+3. Commit your changes (`git commit -am 'Add quantum circuit breaker'`)
+4. Push to the branch (`git push origin feature/save-the-fleet`)
+5. Create a new Pull Request (and wait for the Council of Elders to review)
+
+## License
+
+MIT License. See [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- The `state_machines` gem - The reliable engine under our hood
+- Every service that ever timed out - You taught me well
+- The RMNS Atlas Monkey - For philosophical guidance
+- The Resistance - For never giving up
+
+## Author
+
+Built with ❤️ and ☕ by the Resistance against cascading failures.
+
+**Remember: In space, nobody can hear your Redis timeout. But they can feel your circuit breaker failing over to localhost.**

data/ext/breaker_machines_native/extconf.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ffi/extconf'

data/lib/breaker_machines/async_circuit.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Requires async gem ~> 2.31.0 for modern async patterns
+
+require_relative 'circuit/async_state_management'
+
+module BreakerMachines
+  # AsyncCircuit provides a circuit breaker with async-enabled state machine
+  # for thread-safe, fiber-safe concurrent operations
+  class AsyncCircuit < Circuit
+    include Circuit::AsyncStateManagement
+
+    # Additional async-specific methods
+    def call_async(&block)
+      require 'async' unless defined?(::Async)
+
+      Async do
+        call(&block)
+      end
+    end
+
+    # Fire state transition events asynchronously
+    # @param event_name [Symbol] The event to fire
+    # @return [Async::Task] The async task
+    def fire_async(event_name)
+      require 'async' unless defined?(::Async)
+
+      fire_event_async(event_name)
+    end
+
+    # Check circuit health asynchronously
+    # Useful for monitoring multiple circuits concurrently
+    def health_check_async
+      require 'async' unless defined?(::Async)
+
+      Async do
+        {
+          name: @name,
+          status: status_name,
+          open: open?,
+          stats: stats.to_h,
+          can_recover: open? && reset_timeout_elapsed?
+        }
+      end
+    end
+  end
+end

data/lib/breaker_machines/async_support.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# This file contains all async-related functionality for fiber-safe mode
+# It is only loaded when fiber_safe mode is enabled
+# Requires async gem ~> 2.31.0 for modern timeout API and Promise features
+
+require 'async'
+require 'async/task'
+
+module BreakerMachines
+  # AsyncSupport provides fiber-safe execution capabilities using the async gem
+  module AsyncSupport
+    extend ActiveSupport::Concern
+
+    # Returns the Async::TimeoutError class if available
+    def async_timeout_error_class
+      ::Async::TimeoutError
+    end
+
+    # Execute a call with async support (fiber-safe mode)
+    def execute_call_async(&)
+      start_time = BreakerMachines.monotonic_time
+
+      begin
+        # Execute with hedged requests if enabled
+        result = if @config[:hedged_requests] || @config[:backends]
+                   execute_hedged(&)
+                 else
+                   execute_with_async_timeout(@config[:timeout], &)
+                 end
+
+        record_success(BreakerMachines.monotonic_time - start_time)
+        handle_success
+        result
+      rescue StandardError => e
+        # Re-raise if it's not an async timeout or configured exception
+        raise unless e.is_a?(async_timeout_error_class) || @config[:exceptions].any? { |klass| e.is_a?(klass) }
+
+        record_failure(BreakerMachines.monotonic_time - start_time, e)
+        handle_failure
+        raise unless @config[:fallback]
+
+        invoke_fallback_with_async(e)
+      end
+    end
+
+    # Execute a block with optional timeout using modern Async API
+    def execute_with_async_timeout(timeout, &)
+      if timeout
+        # Use modern timeout API - the flexible with_timeout API is on the task level
+        Async::Task.current.with_timeout(timeout, &)
+      else
+        yield
+      end
+    end
+
+    # Invoke fallback in async context
+    def invoke_fallback_with_async(error)
+      case @config[:fallback]
+      when BreakerMachines::DSL::ParallelFallbackWrapper
+        invoke_parallel_fallbacks(@config[:fallback].fallbacks, error)
+      when Proc
+        result = if @config[:owner]
+                   @config[:owner].instance_exec(error, &@config[:fallback])
+                 else
+                   @config[:fallback].call(error)
+                 end
+
+        # If the fallback returns an Async::Task, wait for it
+        result.is_a?(::Async::Task) ? result.wait : result
+      when Array
+        # Try each fallback in order until one succeeds
+        last_error = error
+        @config[:fallback].each do |fallback|
+          return invoke_single_fallback_async(fallback, last_error)
+        rescue StandardError => e
+          last_error = e
+        end
+        raise last_error
+      else
+        # Static values (strings, hashes, etc.) or Symbol fallbacks
+        @config[:fallback]
+      end
+    end
+
+    private
+
+    def invoke_single_fallback_async(fallback, error)
+      case fallback
+      when Proc
+        result = if @config[:owner]
+                   @config[:owner].instance_exec(error, &fallback)
+                 else
+                   fallback.call(error)
+                 end
+
+        # If the fallback returns an Async::Task, wait for it
+        result.is_a?(::Async::Task) ? result.wait : result
+      else
+        fallback
+      end
+    end
+  end
+end

data/lib/breaker_machines/cascading_circuit.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require_relative 'coordinated_circuit'
+
+module BreakerMachines
+  # CascadingCircuit extends the CoordinatedCircuit class with the ability to automatically
+  # trip dependent circuits when this circuit opens. This enables sophisticated
+  # failure cascade modeling, similar to how critical system failures in a starship
+  # would cascade to dependent subsystems.
+  #
+  # @example Starship network dependency
+  #   # Network circuit that cascades to dependent systems
+  #   network_circuit = BreakerMachines::CascadingCircuit.new('subspace_network', {
+  #     failure_threshold: 1,
+  #     cascades_to: ['weapons_targeting', 'navigation_sensors', 'communications'],
+  #     emergency_protocol: :red_alert
+  #   })
+  #
+  #   # When network fails, all dependent systems are automatically tripped
+  #   network_circuit.call { raise 'Subspace relay offline!' }
+  #   # => All dependent circuits are now open
+  #
+  class CascadingCircuit < CoordinatedCircuit
+    attr_reader :dependent_circuits, :emergency_protocol
+
+    def initialize(name, config = {})
+      @dependent_circuits = Array(config.delete(:cascades_to))
+      @emergency_protocol = config.delete(:emergency_protocol)
+
+      super
+    end
+
+    # Override the trip method to include cascading behavior
+    def trip!
+      result = super
+      perform_cascade if result && @dependent_circuits.any?
+      result
+    end
+
+    # Force cascade failure to all dependent circuits
+    def cascade_failure!
+      perform_cascade
+    end
+
+    # Get the current status of all dependent circuits
+    def dependent_status
+      return {} if @dependent_circuits.empty?
+
+      @dependent_circuits.each_with_object({}) do |circuit_name, status|
+        circuit = BreakerMachines.registry.find(circuit_name)
+        status[circuit_name] = circuit ? circuit.status_name : :not_found
+      end
+    end
+
+    # Check if any dependent circuits are open
+    def dependents_compromised?
+      @dependent_circuits.any? do |circuit_name|
+        circuit = BreakerMachines.registry.find(circuit_name)
+        circuit&.open?
+      end
+    end
+
+    # Summary that includes cascade information
+    def summary
+      base_summary = super
+      return base_summary if @dependent_circuits.empty?
+
+      if @cascade_triggered_at&.value
+        compromised_count = dependent_status.values.count(:open)
+        " CASCADE TRIGGERED: #{compromised_count}/#{@dependent_circuits.length} dependent systems compromised."
+      else
+        " Monitoring #{@dependent_circuits.length} dependent systems."
+      end
+
+      base_summary + cascade_info_text
+    end
+
+    # Provide cascade info for introspection
+    def cascade_info
+      BreakerMachines::CascadeInfo.new(
+        dependent_circuits: @dependent_circuits,
+        emergency_protocol: @emergency_protocol,
+        cascade_triggered_at: @cascade_triggered_at&.value,
+        dependent_status: dependent_status
+      )
+    end
+
+    private
+
+    def perform_cascade
+      return if @dependent_circuits.empty?
+
+      cascade_results = []
+      @cascade_triggered_at ||= Concurrent::AtomicReference.new
+      @cascade_triggered_at.value = BreakerMachines.monotonic_time
+
+      @dependent_circuits.each do |circuit_name|
+        # First try to find circuit in registry
+        circuit = BreakerMachines.registry.find(circuit_name)
+
+        # If not found and we have an owner, try to get it from the owner
+        if !circuit && @config[:owner]
+          owner = @config[:owner]
+          # Handle WeakRef if present
+          owner = owner.__getobj__ if owner.is_a?(WeakRef)
+
+          circuit = owner.circuit(circuit_name) if owner.respond_to?(:circuit)
+        end
+
+        next unless circuit
+        next unless circuit.closed? || circuit.half_open?
+
+        # Force the dependent circuit to open
+        circuit.force_open!
+        cascade_results << circuit_name
+
+        BreakerMachines.instrument('cascade_failure', {
+                                     source_circuit: @name,
+                                     target_circuit: circuit_name,
+                                     emergency_protocol: @emergency_protocol
+                                   })
+      end
+
+      # Trigger emergency protocol if configured
+      trigger_emergency_protocol(cascade_results) if @emergency_protocol && cascade_results.any?
+
+      # Invoke cascade callback if configured
+      if @config[:on_cascade]
+        begin
+          @config[:on_cascade].call(cascade_results) if @config[:on_cascade].respond_to?(:call)
+        rescue StandardError => e
+          # Log callback error but don't fail the cascade
+          BreakerMachines.logger&.error "Cascade callback error: #{e.message}"
+        end
+      end
+
+      cascade_results
+    end
+
+    def trigger_emergency_protocol(affected_circuits)
+      BreakerMachines.instrument('emergency_protocol_triggered', {
+                                   protocol: @emergency_protocol,
+                                   source_circuit: @name,
+                                   affected_circuits: affected_circuits
+                                 })
+
+      # Allow custom emergency protocol handling
+      owner = @config[:owner]
+      if owner.respond_to?(@emergency_protocol, true)
+        begin
+          owner.send(@emergency_protocol, affected_circuits)
+        rescue StandardError => e
+          BreakerMachines.logger&.error "Emergency protocol error: #{e.message}"
+        end
+      elsif respond_to?(@emergency_protocol, true)
+        begin
+          send(@emergency_protocol, affected_circuits)
+        rescue StandardError => e
+          BreakerMachines.logger&.error "Emergency protocol error: #{e.message}"
+        end
+      end
+    end
+
+    # Override the on_circuit_open callback to include cascading
+    def on_circuit_open
+      super # Call the original implementation
+      perform_cascade if @dependent_circuits.any?
+    end
+
+    # Force open should also cascade
+    def force_open!
+      result = super
+      perform_cascade if result && @dependent_circuits.any?
+      result
+    end
+  end
+end

data/lib/breaker_machines/circuit/async_state_management.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module BreakerMachines
+  class Circuit
+    # AsyncStateManagement provides state machine functionality with async support
+    # leveraging state_machines' async: true parameter for thread-safe operations
+    module AsyncStateManagement
+      extend ActiveSupport::Concern
+
+      included do
+        # Enable async mode for thread-safe state transitions
+        # This automatically provides:
+        # - Mutex-protected state reads/writes
+        # - Fiber-safe execution
+        # - Concurrent transition handling
+        state_machine :status, initial: :closed, async: true do
+          event :trip do
+            transition closed: :open
+            transition half_open: :open
+          end
+
+          event :attempt_recovery do
+            transition open: :half_open
+          end
+
+          event :reset do
+            transition %i[open half_open] => :closed
+            transition closed: :closed
+          end
+
+          event :force_open do
+            transition any => :open
+          end
+
+          event :force_close do
+            transition any => :closed
+          end
+
+          event :hard_reset do
+            transition any => :closed
+          end
+
+          before_transition on: :hard_reset do |circuit|
+            circuit.storage&.clear(circuit.name)
+            circuit.half_open_attempts.value = 0
+            circuit.half_open_successes.value = 0
+          end
+
+          # Async-safe callbacks using modern API
+          after_transition to: :open do |circuit|
+            circuit.send(:on_circuit_open)
+          end
+
+          after_transition to: :closed do |circuit|
+            circuit.send(:on_circuit_close)
+          end
+
+          after_transition from: :open, to: :half_open do |circuit|
+            circuit.send(:on_circuit_half_open)
+          end
+        end
+
+        # Additional async event methods are automatically generated:
+        # - trip_async! - Returns Async::Task
+        # - attempt_recovery_async! - Returns Async::Task
+        # - reset_async! - Returns Async::Task
+        # - fire_event_async(:event_name) - Generic async event firing
+      end
+    end
+  end
+end

data/lib/breaker_machines/circuit/base.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+
+module BreakerMachines
+  class Circuit
+    # Base provides the common initialization and setup logic shared by all circuit types
+    module Base
+      extend ActiveSupport::Concern
+
+      included do
+        include Circuit::Configuration
+        include Circuit::Execution
+        include Circuit::HedgedExecution
+        include Circuit::Introspection
+        include Circuit::Callbacks
+        include Circuit::StateCallbacks
+
+        # name/config/opened_at readers are defined in Circuit::Configuration
+        attr_reader :storage, :metrics, :semaphore
+        attr_reader :half_open_attempts, :half_open_successes, :mutex
+        attr_reader :last_failure_at, :last_error
+      end
+
+      def initialize(name, options = {})
+        @name = name
+        @config = default_config.merge(options)
+        # Always use a storage backend for proper sliding window implementation
+        # Use global default storage if not specified
+        @storage = @config[:storage] || create_default_storage
+        @metrics = @config[:metrics]
+        @opened_at = Concurrent::AtomicReference.new(nil)
+        @half_open_attempts = Concurrent::AtomicFixnum.new(0)
+        @half_open_successes = Concurrent::AtomicFixnum.new(0)
+        @mutex = Concurrent::ReentrantReadWriteLock.new
+        @last_failure_at = Concurrent::AtomicReference.new(nil)
+        @last_error = Concurrent::AtomicReference.new(nil)
+
+        # Initialize semaphore for bulkheading if max_concurrent is set
+        @semaphore = (Concurrent::Semaphore.new(@config[:max_concurrent]) if @config[:max_concurrent])
+
+        restore_status_from_storage if @storage
+
+        # Register with global registry unless auto_register is disabled
+        BreakerMachines::Registry.instance.register(self) unless @config[:auto_register] == false
+      end
+
+      private
+
+      def restore_status_from_storage
+        stored_status = @storage.get_status(@name)
+        return unless stored_status
+
+        self.status = stored_status.status.to_s
+        @opened_at.value = stored_status.opened_at if stored_status.opened_at
+      end
+    end
+  end
+end