rails_health_checks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a376b4d6a5d680684058c1c123903ebc889e48ffa38cfd937cec29d53ebdaf6
+  data.tar.gz: c5aabce9da9a24785ae363f97cf0781f6a26184a53bfaa6d629fcea671c80189
+SHA512:
+  metadata.gz: 35b074807441355e162b1c9bdccf1303ed3ce9c8b125fd6043676261e297c362cce28d3fb651555476c2a14f84ab282a18f1e59bf6b2e10a2e4c7268cab13603
+  data.tar.gz: e5c9a043d6627f7bbfc8015d6104b679c1f80b99ec23952b353024c037e2c50954af36f1926e404005ab83a8637c360b92dd66e9aaa3722d852b865cd7111beb

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright TODO: Write your name
+
+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,112 @@
+# RailsHealthChecks
+
+[![CI](https://github.com/eclectic-coding/rails_health_checks/actions/workflows/ci.yml/badge.svg)](https://github.com/eclectic-coding/rails_health_checks/actions/workflows/ci.yml)
+[![gem](https://badge.fury.io/rb/rails_health_checks.svg)](https://badge.fury.io/rb/rails_health_checks)
+[![downloads](https://img.shields.io/gem/dt/rails_health_checks.svg)](https://rubygems.org/gems/rails_health_checks)
+[![ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-ruby.svg)](https://www.ruby-lang.org)
+[![codecov](https://codecov.io/gh/eclectic-coding/rails_health_checks/branch/main/graph/badge.svg)](https://codecov.io/gh/eclectic-coding/rails_health_checks)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Rails engine providing structured, pluggable health check endpoints for monitoring application status. Goes beyond Rails' built-in `/up` endpoint with per-check diagnostics, latency tracking, and a configurable check registry.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Endpoints](#endpoints)
+- [Configuration](#configuration)
+- [Built-in Checks](#built-in-checks)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "rails_health_checks"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+mount RailsHealthChecks::Engine => "/health"
+```
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## Endpoints
+
+| Endpoint | Format | Use case |
+|----------|--------|----------|
+| `GET /health` | JSON | Monitoring dashboards, detailed diagnostics |
+| `GET /health/live` | Plain text | Load balancer liveness probes |
+
+HTTP status is `200 OK` when all checks pass, `503 Service Unavailable` otherwise.
+
+### JSON response shape
+
+```json
+{
+  "status": "ok",
+  "timestamp": "2026-06-08T20:00:00Z",
+  "checks": {
+    "database": { "status": "ok", "latency_ms": 4 }
+  }
+}
+```
+
+Status values: `ok` | `degraded` | `critical`. Overall status is `critical` if any check is `critical`, `degraded` if any is `degraded`.
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## Configuration
+
+```ruby
+# config/initializers/rails_health_checks.rb
+RailsHealthChecks.configure do |config|
+  config.checks  = [:database]  # checks to run (default: [:database])
+  config.timeout = 5            # global timeout per check in seconds (default: 5)
+end
+```
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## Built-in Checks
+
+| Check | Description |
+|-------|-------------|
+| `:database` | ActiveRecord `SELECT 1` against the primary connection, includes latency |
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
+require 'bundler/audit/task'
+require 'rspec/core/rake_task'
+
+RuboCop::RakeTask.new(:lint)
+Bundler::Audit::Task.new
+RSpec::Core::RakeTask.new(:spec)
+
+task default: [:lint, :'bundle:audit:update', 'bundle:audit:check', :spec]

data/app/controllers/rails_health_checks/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class ApplicationController < ActionController::API
+  end
+end

data/app/controllers/rails_health_checks/health_controller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class HealthController < ApplicationController
+    def show
+      builder = ResponseBuilder.new(run_checks)
+      render json: builder.to_json, status: builder.http_status
+    end
+
+    def live
+      builder = ResponseBuilder.new(run_checks)
+      if builder.overall_status == "ok"
+        render plain: "OK", status: :ok
+      else
+        render plain: "Service Unavailable", status: :service_unavailable
+      end
+    end
+
+    private
+
+    def run_checks
+      config = RailsHealthChecks.configuration
+      checks = CheckRegistry.build(config.checks)
+      CheckRegistry.run(checks, timeout: config.timeout)
+    end
+  end
+end

data/app/jobs/rails_health_checks/application_job.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/rails_health_checks/application_mailer.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/rails_health_checks/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+RailsHealthChecks::Engine.routes.draw do
+  get "/",     to: "health#show", as: :health
+  get "/live", to: "health#live", as: :health_live
+end

data/lib/rails_health_checks/check.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class Check
+    attr_reader :status, :message, :latency_ms
+
+    def call
+      raise NotImplementedError, "#{self.class} must implement #call"
+    end
+
+    private
+
+    def pass(message = nil)
+      @status = "ok"
+      @message = message
+    end
+
+    def warn_with(message)
+      @status = "degraded"
+      @message = message
+    end
+
+    def fail_with(message)
+      @status = "critical"
+      @message = message
+    end
+
+    def measure
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      yield
+      @latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+    end
+  end
+end

data/lib/rails_health_checks/check_registry.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module RailsHealthChecks
+  class CheckRegistry
+    BUILT_INS = {
+      database: -> { Checks::DatabaseCheck.new }
+    }.freeze
+
+    def self.build(check_names)
+      check_names.each_with_object({}) do |name, hash|
+        factory = BUILT_INS.fetch(name) do
+          raise ArgumentError, "Unknown check: #{name}. Available: #{BUILT_INS.keys.join(', ')}"
+        end
+        hash[name] = factory.call
+      end
+    end
+
+    def self.run(checks, timeout:)
+      checks.transform_values { |check| run_check(check, timeout: timeout) }
+    end
+
+    def self.run_check(check, timeout:)
+      Timeout.timeout(timeout) { check.call }
+      check
+    rescue Timeout::Error
+      mark_critical(check, "timed out")
+    rescue StandardError => e
+      mark_critical(check, e.message)
+    end
+
+    def self.mark_critical(check, message)
+      check.instance_variable_set(:@status, "critical")
+      check.instance_variable_set(:@message, message)
+      check
+    end
+
+    private_class_method :run_check, :mark_critical
+  end
+end

data/lib/rails_health_checks/checks/database_check.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  module Checks
+    class DatabaseCheck < Check
+      def call
+        measure { ActiveRecord::Base.connection.execute("SELECT 1") }
+        pass
+      rescue StandardError => e
+        fail_with(e.message)
+      end
+    end
+  end
+end

data/lib/rails_health_checks/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class Configuration
+    attr_accessor :checks, :timeout
+
+    def initialize
+      @checks = [:database]
+      @timeout = 5
+    end
+  end
+end

data/lib/rails_health_checks/engine.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsHealthChecks
+    config.generators.api_only = true
+  end
+end

data/lib/rails_health_checks/response_builder.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class ResponseBuilder
+    def initialize(results)
+      @results = results
+    end
+
+    def overall_status
+      statuses = @results.values.map(&:status)
+      if statuses.include?("critical")
+        "critical"
+      elsif statuses.include?("degraded")
+        "degraded"
+      else
+        "ok"
+      end
+    end
+
+    def to_json(*)
+      checks_hash = @results.transform_values do |check|
+        result = { status: check.status }
+        result[:latency_ms] = check.latency_ms if check.latency_ms
+        result[:message] = check.message if check.message
+        result
+      end
+
+      { status: overall_status, timestamp: Time.now.utc.iso8601, checks: checks_hash }.to_json
+    end
+
+    def http_status
+      overall_status == "ok" ? :ok : :service_unavailable
+    end
+  end
+end

data/lib/rails_health_checks/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  VERSION = "0.1.0"
+end

data/lib/rails_health_checks.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails_health_checks/version"
+require "rails_health_checks/engine"
+require "rails_health_checks/configuration"
+require "rails_health_checks/check"
+require "rails_health_checks/checks/database_check"
+require "rails_health_checks/check_registry"
+require "rails_health_checks/response_builder"
+
+module RailsHealthChecks
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+end

data/lib/tasks/rails_health_checks_tasks.rake

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# desc "Explaining what the task does"
+# task :rails_health_checks do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: rails_health_checks
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chuck Smith
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+description: A Rails engine providing configurable health check endpoints for monitoring
+  application status.
+email:
+- chuck@eclecticcoding.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/rails_health_checks/application_controller.rb
+- app/controllers/rails_health_checks/health_controller.rb
+- app/jobs/rails_health_checks/application_job.rb
+- app/mailers/rails_health_checks/application_mailer.rb
+- app/models/rails_health_checks/application_record.rb
+- config/routes.rb
+- lib/rails_health_checks.rb
+- lib/rails_health_checks/check.rb
+- lib/rails_health_checks/check_registry.rb
+- lib/rails_health_checks/checks/database_check.rb
+- lib/rails_health_checks/configuration.rb
+- lib/rails_health_checks/engine.rb
+- lib/rails_health_checks/response_builder.rb
+- lib/rails_health_checks/version.rb
+- lib/tasks/rails_health_checks_tasks.rake
+homepage: https://github.com/eclectic-coding/rails_health_checks
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/eclectic-coding/rails_health_checks
+  source_code_uri: https://github.com/eclectic-coding/rails_health_checks
+  changelog_uri: https://github.com/eclectic-coding/rails_health_checks/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Health check endpoints for Rails applications.
+test_files: []