Simple configurable application healthcheck rack middleware. This middleware allows you to embed healthcheck endpoints into your rack based application to perform healthcheck probes. Make your application compatible with Docker/Kubernetes healthchecks in a seconds.

Table of Contents

• Features
• Requirements
• Installation
• Configuring
• Usage
  • Integration
    • Rack
    • Roda
    • Hanami
    • Rails
  • Healthcheck endpoint response
• Contributing
• License
• Code of Conduct
• Credits
• Versioning
• Changelog

Features

• Built-in default configuration
• Configurable services for startup/liveness/readiness probes
• Configurable root endpoints namespace
• Configurable startup/liveness/readiness probes endpoints
• Configurable successful/failure response statuses

Requirements

Ruby MRI 2.5.0+

Installation

Add this line to your application's Gemfile:

gem 'healthcheck_endpoint'

And then execute:

bundle

Or install it yourself as:

gem install healthcheck_endpoint

Configuring

To start working with this gem, you must configure it first as in the example below:

# config/initializers/healthcheck_endpoint.rb

require 'healthcheck_endpoint'

HealthcheckEndpoint.configure do |config|
  # Optional parameter. The list of services that can be triggered
  # during running probes. Each value of this hash should be callable
  # and return boolean.
  # It is equal to empty hash by default.
  config.services = {
    postgres: -> { true },
    redis: -> { true },
    rabbit: -> { false }
  }

  # Optional parameter. The list of services that will be checked
  # during running startup probe. As array items must be used an
  # existing keys, defined in config.services.
  # It is equal to empty array by default.
  config.services_startup = %i[postgres]

  # Optional parameter. The list of services that will be checked
  # during running liveness probe. As array items must be used an
  # existing keys, defined in config.services.
  # It is equal to empty array by default.
  config.services_liveness = %i[redis]

  # Optional parameter. The list of services that will be checked
  # during running liveness probe. As array items must be used an
  # existing keys, defined in config.services.
  # It is equal to empty array by default.
  config.services_readiness = %i[postgres redis rabbit]

  # Optional parameter. The name of middleware's root
  # endpoints namespace. Use '/' if you want to use root
  # namespace. It is equal to /healthcheck by default.
  config.endpoints_namespace = '/application-healthcheck'

  # Optional parameter. The startup endpoint path.
  # It is equal to /startup by default.
  config.endpoint_startup = '/startup-probe'

  # Optional parameter. The liveness endpoint path.
  # It is equal to /liveness by default.
  config.endpoint_liveness = '/liveness-probe'

  # Optional parameter. The readiness endpoint path.
  # It is equal to /readiness by default.
  config.endpoint_readiness = '/readiness-probe'

  # Optional parameter. The HTTP successful status
  # for startup probe. It is equal to 200 by default.
  config.endpoint_startup_status_success = 201

  # Optional parameter. The HTTP successful status
  # for liveness probe. It is equal to 200 by default.
  config.endpoint_liveness_status_success = 202
  
  # Optional parameter. The HTTP successful status
  # for readiness probe. It is equal to 200 by default.
  config.endpoint_readiness_status_success = 203

  # Optional parameter. The HTTP failure status
  # for startup probe. It is equal to 500 by default.
  config.endpoint_startup_status_failure = 501

  # Optional parameter. The HTTP failure status
  # for liveness probe. It is equal to 500 by default.
  config.endpoint_liveness_status_failure = 502

  # Optional parameter. The HTTP failure status
  # for readiness probe. It is equal to 500 by default.
  config.endpoint_readiness_status_failure = 503
end

Usage

Integration

Please note, to start using this middleware you should configure HealthcheckEndpoint before and then you should to add HealthcheckEndpoint::RackMiddleware on the top of middlewares list.

Rack

require 'healthcheck_endpoint'

# Configuring HealthcheckEndpoint with default settings
HealthcheckEndpoint.configure

Rack::Builder.app do
  use HealthcheckEndpoint::RackMiddleware
  run YourApplication
end

Roda

require 'healthcheck_endpoint'

# Configuring HealthcheckEndpoint with default settings
HealthcheckEndpoint.configure

class YourApplication < Roda
  use HealthcheckEndpoint::RackMiddleware
end

Hanami

# config/initializers/healthcheck_endpoint.rb

require 'healthcheck_endpoint'

# Configuring HealthcheckEndpoint with default settings
HealthcheckEndpoint.configure

# config/environment.rb

Hanami.configure do
  middleware.use HealthcheckEndpoint::RackMiddleware
end

Rails

For Rails 7+, you can use the built-in healthcheck feature provided by Rails itself. See the official Rails documentation on healthchecks for details. However, if you need more advanced healthcheck functionality or want to maintain consistency across different frameworks, you can still use this gem with Rails as follows:

# config/initializers/healthcheck_endpoint.rb

require 'healthcheck_endpoint'

# Configuring HealthcheckEndpoint with default settings
HealthcheckEndpoint.configure

# config/application.rb

class Application < Rails::Application
  config.middleware.use HealthcheckEndpoint::RackMiddleware
end

Healthcheck endpoint response

Each healthcheck endpoint returns proper HTTP status and body. Determining the response status is based on the general result of service checks (when all are successful the status is successful, at least one failure - the status is failure). The response body represented as JSON document with a structure like in the example below:

{
  "data": {
    "id": "a09efd18-e09f-4207-9a43-b4bf89f76b47",
    "type": "application-startup-healthcheck",
    "attributes": {
        "postgres": true,
        "redis": true,
        "rabbit": true
    }
  }
}

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/obstools/healthcheck-endpoint. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct. Please check the open tickets. Be sure to follow Contributor Code of Conduct below and our Contributing Guidelines.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the healthcheck_endpoint project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Credits

• The Contributors for code and awesome suggestions
• The Stargazers for showing their support

Versioning

healthcheck_endpoint uses Semantic Versioning 2.0.0