philiprehberger-circuit

Minimal circuit breaker with configurable thresholds, error filtering, and exponential backoff

Requirements

Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-circuit"

Or install directly:

gem install philiprehberger-circuit

Usage

require "philiprehberger/circuit"

breaker = Philiprehberger::Circuit::Breaker.new(:payment_api, threshold: 5, timeout: 30)

breaker.call do
  PaymentGateway.charge(amount)
end
# After 5 failures -> circuit opens -> raises OpenError for 30s
# After 30s -> half-open -> allows one probe request

Fallback

Return a fallback value when the circuit is open instead of raising:

breaker.call(fallback: -> { :queued }) do
  PaymentGateway.charge(amount)
end

Error Filtering

breaker = Philiprehberger::Circuit::Breaker.new(:api, error_classes: [Net::TimeoutError, Net::OpenTimeout])

Half-Open Control

Limit the number of probe requests allowed in half-open state:

breaker = Philiprehberger::Circuit::Breaker.new(:api, half_open_requests: 2)
# Only 2 requests pass through in half-open; the rest are rejected

Metrics

Access counters for monitoring:

breaker.metrics
# => { success_count: 42, failure_count: 3, rejected_count: 7, state_changes: [...] }

Each state change entry contains { from:, to:, at: } with the transition timestamp.

Last Failure

Inspect the most recent failure recorded by the breaker for diagnostics. Returns nil when no failure has happened since the last reset.

breaker.call { raise Net::OpenTimeout, 'connection refused' } rescue nil

breaker.last_failure
# => { at: 2026-04-28 14:32:08 +0000, error_class: Net::OpenTimeout, message: "connection refused" }

last_failure is captured for both closed-state failures and half-open probe failures, and is cleared by #metrics_reset!.

Resetting metrics

Zero the counters and clear the state-change log without touching the current state (useful for periodic metric windows):

breaker.metrics_reset!
breaker.metrics
# => { success_count: 0, failure_count: 0, rejected_count: 0, state_changes: [] }
# breaker.state is unchanged

Exponential Backoff

Use exponential backoff for the open-to-half-open timeout:

breaker = Philiprehberger::Circuit::Breaker.new(
  :api,
  timeout_strategy: :exponential,
  base_timeout: 10,
  max_timeout: 300
)
# Timeouts double on each consecutive open: 20s, 40s, 80s, ... capped at 300s
# Resets to base_timeout when circuit closes

Event Callbacks

breaker.on_open { AlertService.notify("Circuit opened!") }
breaker.on_close { AlertService.notify("Circuit recovered") }
breaker.on_half_open { Logger.info("Circuit probing...") }

Force trip

Administratively force the circuit into the open state, regardless of current state or failure count:

breaker.trip!
breaker.state # => :open

# Subsequent calls short-circuit like any other open-state call
breaker.call(fallback: -> { :queued }) { PaymentGateway.charge(amount) }
# => :queued

State Predicates

Idiomatic predicate methods for testing the current state without comparing against state symbols:

breaker.closed?    # => true (fresh breaker)
breaker.open?      # => false
breaker.half_open? # => false

breaker.trip!
breaker.open?      # => true
breaker.closed?    # => false

Manual Control

Force the breaker into a fixed state for maintenance windows. While forced, automatic state transitions (failure-based opening, timeout-based half-open probes) are suspended until reset! is called:

# Force open during a maintenance window — rejects all calls regardless of timeout
breaker.force_open!
breaker.forced? # => true
breaker.call { :anything } # => raises OpenError

# Force closed to bypass the breaker entirely — accepts all calls, ignores failures
breaker.force_closed!
breaker.forced? # => true

# Clear the forced flag and return to normal automatic behavior
breaker.reset!
breaker.forced? # => false

Reset Callback

Hook into every state transition for logging or alerting:

breaker.on_reset do |from_state, to_state|
  Logger.info("Circuit #{breaker.name} transitioned from #{from_state} to #{to_state}")
end

API

Method	Description
`Breaker.new(name, **opts)`	Create a breaker (see options below)
`#call(fallback: nil) { block }`	Execute with circuit protection
`#state`	Current state (`:closed`, `:open`, `:half_open`)
`#closed?` / `#open?` / `#half_open?`	State predicates
`#reset!`	Force back to closed
`#trip!`	Force open (administrative trip)
`#force_open!`	Force open and suspend automatic transitions until `#reset!`
`#force_closed!`	Force closed and suspend automatic transitions until `#reset!`
`#forced?`	Whether the breaker is in a manually forced state
`#metrics`	Returns `{ success_count:, failure_count:, rejected_count:, state_changes: [] }`
`#last_failure`	Returns `{ at:, error_class:, message: }` for the most recent failure (or `nil`)
`#metrics_reset!`	Zero counters and clear state-change log without altering current state
`#on_open { }`	Callback when circuit opens
`#on_close { }`	Callback when circuit closes
`#on_half_open { }`	Callback when circuit enters half-open
`#on_reset { \|from, to\| }`	Callback on every state transition

Constructor Options

Option	Default	Description
`threshold:`	`5`	Failures before opening
`timeout:`	`30`	Seconds before trying half-open (fixed strategy)
`error_classes:`	`[StandardError]`	Exception classes to count
`half_open_requests:`	`1`	Max probe requests in half-open
`timeout_strategy:`	`:fixed`	`:fixed` or `:exponential`
`base_timeout:`	`timeout`	Base timeout for exponential backoff
`max_timeout:`	`base * 32`	Max timeout cap for exponential backoff

Development

bundle install
bundle exec rspec
bundle exec rubocop

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT