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
gem ' breaker_machines '
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
circuit breaker implementation Fiber-safe mode for async Ruby (Falcon, async gem)
for async Ruby (Falcon, async gem) Hedged requests for latency reduction
for latency reduction Multiple backends with automatic failover
with automatic failover Bulkheading to limit concurrent requests
to limit concurrent requests Percentage-based thresholds with minimum call requirements
with minimum call requirements Dynamic circuit breakers with templates for runtime creation
with templates for runtime creation Pluggable storage (Memory, Redis, Custom)
(Memory, Redis, Custom) Rich callbacks and instrumentation
and instrumentation ActiveSupport::Notifications integration
Documentation
Getting Started Guide (docs/GETTING_STARTED.md) - Installation and basic usage
(docs/GETTING_STARTED.md) - Installation and basic usage Configuration Reference (docs/CONFIGURATION.md) - All configuration options
(docs/CONFIGURATION.md) - All configuration options Advanced Patterns (docs/ADVANCED_PATTERNS.md) - Complex scenarios and patterns
(docs/ADVANCED_PATTERNS.md) - Complex scenarios and patterns Persistence Options (docs/PERSISTENCE.md) - Storage backends and distributed state
(docs/PERSISTENCE.md) - Storage backends and distributed state Observability Guide (docs/OBSERVABILITY.md) - Monitoring and metrics
(docs/OBSERVABILITY.md) - Monitoring and metrics Async Mode (docs/ASYNC.md) - Fiber-safe operations
(docs/ASYNC.md) - Fiber-safe operations Testing Guide (docs/TESTING.md) - Testing strategies RSpec Testing ActiveSupport Testing
(docs/TESTING.md) - Testing strategies Rails Integration (docs/RAILS_INTEGRATION.md) - Rails-specific patterns
(docs/RAILS_INTEGRATION.md) - Rails-specific patterns Horror Stories (docs/HORROR_STORIES.md) - Real production failures and lessons learned
(docs/HORROR_STORIES.md) - Real production failures and lessons learned API Reference (docs/API_REFERENCE.md) - Complete API documentation
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 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:
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 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 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
- Reduce latency with duplicate requests Multiple Backends - Automatic failover across endpoints
- Automatic failover across endpoints Percentage-Based Thresholds - Open on error rates, not just counts
- Open on error rates, not just counts Dynamic Circuit Breakers - Runtime creation with templates
- Runtime creation with templates Apocalypse-Resistant Storage - Cascading fallbacks when Redis dies
- Cascading fallbacks when Redis dies Custom Storage Backends - SysV semaphores, distributed locks, etc.
See Advanced Patterns 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
Fork it (like it's 2005) Create your feature branch ( git checkout -b feature/save-the-fleet ) Commit your changes ( git commit -am 'Add quantum circuit breaker' ) Push to the branch ( git push origin feature/save-the-fleet ) Create a new Pull Request (and wait for the Council of Elders to review)
License
MIT License. See LICENSE file for details.
Acknowledgments
The state_machines gem - The reliable engine under our hood
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.