philiprehberger-circuit_board

Health check framework with dependency aggregation and Rack endpoint

Requirements

• Ruby >= 3.1

Installation

Add to your Gemfile:

gem "philiprehberger-circuit_board"

Or install directly:

gem install philiprehberger-circuit_board

Usage

require "philiprehberger/circuit_board"

Philiprehberger::CircuitBoard.configure do
  check(:database) { ActiveRecord::Base.connection.active? }
  check(:redis, timeout: 2) { Redis.current.ping == 'PONG' }
end

status = Philiprehberger::CircuitBoard.check
status.healthy?   # => true
status.degraded?  # => false
status.to_h       # => { status: 'healthy', checks: [...] }

Single Check

result = Philiprehberger::CircuitBoard.check_one(:database)
# => { name: :database, healthy: true, duration: 0.0012 }

Raises Philiprehberger::CircuitBoard::Error if the named check does not exist.

Rack Middleware

# config.ru
require "philiprehberger/circuit_board"

Philiprehberger::CircuitBoard.configure do
  check(:database) { DB.connected? }
end

use Philiprehberger::CircuitBoard::Rack::Middleware
run MyApp

Exposes three endpoints:

• GET /health - full health check with all dependency results
• GET /health/ready - readiness probe (all checks must pass)
• GET /health/live - liveness probe (always returns 200)

Critical and Non-Critical Checks

Philiprehberger::CircuitBoard.configure do
  check(:database) { ActiveRecord::Base.connection.active? }          # critical (default)
  check(:cache, critical: false) { Redis.current.ping == 'PONG' }    # non-critical
end

status = Philiprehberger::CircuitBoard.check
# If only cache fails: status is "degraded"
# If database fails:   status is "unhealthy"

Parallel Execution

Run all checks concurrently for lower latency:

status = Philiprehberger::CircuitBoard.check(parallel: true)
status.healthy?          # => true
status.duration          # => wall-clock time of the slowest check
status.unhealthy_checks  # => []
status.to_json           # => '{"status":"healthy","checks":[...]}'

Caching Expensive Checks

Philiprehberger::CircuitBoard.configure do
  # Cache successful database probe for 30 seconds
  check(:database, cache: 30) { ActiveRecord::Base.connection.active? }
end

# First call hits the DB; subsequent calls within 30s return the cached result.
# Failed checks are never cached — failures re-run on every probe.

Check Timeouts

Philiprehberger::CircuitBoard.configure do
  check(:fast_service, timeout: 1) { FastService.ping }
  check(:slow_service, timeout: 10) { SlowService.ping }
end

State Change Callback

require "philiprehberger/circuit_board"

Philiprehberger::CircuitBoard.configure do |c|
  c.check("database") { ActiveRecord::Base.connection.active? }
  c.on_change do |from, to|
    puts "Health changed: #{from} -> #{to}"
  end
end

API

Method	Description
.configure { ... }	Define health checks using the DSL (check(name, timeout:, critical:, cache:))
.check(parallel: false)	Run all checks and return a Status; parallel: true runs concurrently
.check_one(name)	Run a single named check and return its result hash
.reset!	Remove all configured checks
on_change(&block)	Callback invoked on health status transitions
Status#healthy?	Whether all checks passed
Status#degraded?	Whether some checks passed but not all
Status#to_h	Hash with :status and :checks keys
Status#results	Array of individual check results
Status#unhealthy_checks	Failed check results
Status#healthy_checks	Passed check results
Status#duration	Wall-clock duration of slowest check
Status#to_json	JSON string of to_h
Rack::Middleware.new(app)	Rack middleware for health endpoints

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