healthcheck_endpoint 1.0.0

data/README.md

@@ -0,0 +1,256 @@
+# ![HealthcheckEndpoint - Simple configurable application healthcheck rack middleware](https://repository-images.githubusercontent.com/769335579/012755ac-8757-43b1-8191-7cac167396fa)
+
+[![Maintainability](https://api.codeclimate.com/v1/badges/e1da0941cf2234c1d110/maintainability)](https://codeclimate.com/github/obstools/healthcheck-endpoint/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/e1da0941cf2234c1d110/test_coverage)](https://codeclimate.com/github/obstools/healthcheck-endpoint/test_coverage)
+[![CircleCI](https://circleci.com/gh/obstools/healthcheck-endpoint/tree/master.svg?style=svg)](https://circleci.com/gh/obstools/healthcheck-endpoint/tree/master)
+[![Gem Version](https://badge.fury.io/rb/healthcheck_endpoint.svg)](https://badge.fury.io/rb/healthcheck_endpoint)
+[![Downloads](https://img.shields.io/gem/dt/healthcheck_endpoint.svg?colorA=004d99&colorB=0073e6)](https://rubygems.org/gems/healthcheck_endpoint)
+[![GitHub](https://img.shields.io/github/license/obstools/healthcheck-endpoint)](LICENSE.txt)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
+
+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](https://docs.docker.com/reference/dockerfile/#healthcheck)/[Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-http-request) healthchecks in a seconds.
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuring](#configuring)
+- [Usage](#usage)
+  - [Integration](#integration)
+    - [Rack](#rack)
+    - [Roda](#roda)
+    - [Hanami](#hanami)
+    - [Rails](#rails)
+  - [Healthcheck endpoint response](#healthcheck-endpoint-response)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+- [Credits](#credits)
+- [Versioning](#versioning)
+- [Changelog](CHANGELOG.md)
+
+## 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:
+
+```ruby
+gem 'healthcheck_endpoint'
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+Or install it yourself as:
+
+```bash
+gem install healthcheck_endpoint
+```
+
+## Configuring
+
+To start working with this gem, you must configure it first as in the example below:
+
+```ruby
+# 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
+
+```ruby
+require 'healthcheck_endpoint'
+
+# Configuring HealthcheckEndpoint with default settings
+HealthcheckEndpoint.configure
+
+Rack::Builder.app do
+  use HealthcheckEndpoint::RackMiddleware
+  run YourApplication
+end
+```
+
+#### Roda
+
+```ruby
+require 'healthcheck_endpoint'
+
+# Configuring HealthcheckEndpoint with default settings
+HealthcheckEndpoint.configure
+
+class YourApplication < Roda
+  use HealthcheckEndpoint::RackMiddleware
+end
+```
+
+#### Hanami
+
+```ruby
+# config/initializers/healthcheck_endpoint.rb
+
+require 'healthcheck_endpoint'
+
+# Configuring HealthcheckEndpoint with default settings
+HealthcheckEndpoint.configure
+```
+
+```ruby
+# 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](https://edgeapi.rubyonrails.org/classes/Rails/HealthController.html) 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:
+
+```ruby
+# config/initializers/healthcheck_endpoint.rb
+
+require 'healthcheck_endpoint'
+
+# Configuring HealthcheckEndpoint with default settings
+HealthcheckEndpoint.configure
+```
+
+```ruby
+# 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:
+
+```json
+{
+  "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](http://contributor-covenant.org) code of conduct. Please check the [open tickets](https://github.com/obstools/healthcheck-endpoint/issues). Be sure to follow Contributor Code of Conduct below and our [Contributing Guidelines](CONTRIBUTING.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 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](CODE_OF_CONDUCT.md).
+
+## Credits
+
+- [The Contributors](https://github.com/obstools/healthcheck-endpoint/graphs/contributors) for code and awesome suggestions
+- [The Stargazers](https://github.com/obstools/healthcheck-endpoint/stargazers) for showing their support
+
+## Versioning
+
+`healthcheck_endpoint` uses [Semantic Versioning 2.0.0](https://semver.org)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'healthcheck_endpoint'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/healthcheck_endpoint.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'lib/healthcheck_endpoint/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'healthcheck_endpoint'
+  spec.version       = HealthcheckEndpoint::VERSION
+  spec.authors       = ['Vladislav Trotsenko']
+  spec.email         = %w[admin@bestweb.com.ua]
+  spec.summary       = %(Simple configurable application healthcheck rack middleware)
+  spec.description   = %(Simple configurable application healthcheck rack middleware.)
+  spec.homepage      = 'https://github.com/obstools/healthcheck-endpoint'
+  spec.license       = 'MIT'
+
+  current_ruby_version = ::Gem::Version.new(::RUBY_VERSION)
+  ffaker_version = current_ruby_version >= ::Gem::Version.new('3.0.0') ? '~> 2.23' : '~> 2.21'
+
+  spec.required_ruby_version = '>= 2.5.0'
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.require_paths = %w[lib]
+
+  spec.add_runtime_dependency 'rack', '>= 2.0.1'
+
+  spec.add_development_dependency 'ffaker', ffaker_version
+  spec.add_development_dependency 'json_matchers', '~> 0.11.1'
+  spec.add_development_dependency 'rake', '~> 13.2', '>= 13.2.1'
+  spec.add_development_dependency 'rspec', '~> 3.13'
+end

data/lib/healthcheck_endpoint/configuration.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module HealthcheckEndpoint
+  class Configuration
+    ATTRIBUTES = %i[
+      services
+      services_startup
+      services_liveness
+      services_readiness
+      endpoints_namespace
+      endpoint_startup
+      endpoint_liveness
+      endpoint_readiness
+      endpoint_startup_status_success
+      endpoint_liveness_status_success
+      endpoint_readiness_status_success
+      endpoint_startup_status_failure
+      endpoint_liveness_status_failure
+      endpoint_readiness_status_failure
+    ].freeze
+    ENDPOINTS_NAMESPACE = '/healthcheck'
+    ENDPOINT_STARTUP = '/startup'
+    ENDPOINT_LIVENESS = '/liveness'
+    ENDPOINT_READINESS = '/readiness'
+    DEFAULT_HTTP_STATUS_SUCCESS = 200
+    DEFAULT_HTTP_STATUS_FAILURE = 500
+    AVILABLE_HTTP_STATUSES_SUCCESS = (DEFAULT_HTTP_STATUS_SUCCESS..226).freeze
+    AVILABLE_HTTP_STATUSES_FAILURE = (DEFAULT_HTTP_STATUS_FAILURE..511).freeze
+
+    Settings = ::Struct.new(*HealthcheckEndpoint::Configuration::ATTRIBUTES, keyword_init: true) do
+      def update(&block)
+        return self unless block
+
+        tap(&block)
+      end
+    end
+
+    attr_reader(*HealthcheckEndpoint::Configuration::ATTRIBUTES)
+
+    def initialize(&block)
+      configuration_settings = build_configuration_settings(&block)
+      HealthcheckEndpoint::Configuration::ATTRIBUTES.each do |attribute|
+        public_send(:"#{attribute}=", configuration_settings.public_send(attribute))
+      end
+    end
+
+    HealthcheckEndpoint::Configuration::ATTRIBUTES.each do |attribute|
+      define_method(:"#{attribute}=") do |argument|
+        validate_attribute(__method__, attribute, argument)
+        instance_variable_set(:"@#{attribute}", argument)
+      end
+    end
+
+    private
+
+    def build_configuration_settings(&block) # rubocop:disable Metrics/MethodLength
+      HealthcheckEndpoint::Configuration::Settings.new(
+        services: {},
+        services_startup: [],
+        services_liveness: [],
+        services_readiness: [],
+        endpoints_namespace: HealthcheckEndpoint::Configuration::ENDPOINTS_NAMESPACE,
+        endpoint_startup: HealthcheckEndpoint::Configuration::ENDPOINT_STARTUP,
+        endpoint_liveness: HealthcheckEndpoint::Configuration::ENDPOINT_LIVENESS,
+        endpoint_readiness: HealthcheckEndpoint::Configuration::ENDPOINT_READINESS,
+        endpoint_startup_status_success: HealthcheckEndpoint::Configuration::DEFAULT_HTTP_STATUS_SUCCESS,
+        endpoint_liveness_status_success: HealthcheckEndpoint::Configuration::DEFAULT_HTTP_STATUS_SUCCESS,
+        endpoint_readiness_status_success: HealthcheckEndpoint::Configuration::DEFAULT_HTTP_STATUS_SUCCESS,
+        endpoint_startup_status_failure: HealthcheckEndpoint::Configuration::DEFAULT_HTTP_STATUS_FAILURE,
+        endpoint_liveness_status_failure: HealthcheckEndpoint::Configuration::DEFAULT_HTTP_STATUS_FAILURE,
+        endpoint_readiness_status_failure: HealthcheckEndpoint::Configuration::DEFAULT_HTTP_STATUS_FAILURE
+      ).update(&block)
+    end
+
+    def validate_attribute(method, attribute, value) # rubocop:disable Metrics/AbcSize
+      raise_unless(HealthcheckEndpoint::Error::Configuration::ArgumentType, method, *validator_argument_type(attribute, value))
+      case attribute
+      when HealthcheckEndpoint::Configuration::ATTRIBUTES[0]
+        raise_unless(HealthcheckEndpoint::Error::Configuration::NotCallableService, method, *validator_services_callable(value))
+      when *HealthcheckEndpoint::Configuration::ATTRIBUTES[1..3]
+        raise_unless(HealthcheckEndpoint::Error::Configuration::UnknownService, method, *validator_services_conformity(value))
+      when *HealthcheckEndpoint::Configuration::ATTRIBUTES[4..7]
+        raise_unless(HealthcheckEndpoint::Error::Configuration::EnpointPattern, method, *validator_endpoint(value))
+      when *HealthcheckEndpoint::Configuration::ATTRIBUTES[8..10]
+        raise_unless(HealthcheckEndpoint::Error::Configuration::HttpStatusSuccess, method, *validator_http_status_success(value))
+      when *HealthcheckEndpoint::Configuration::ATTRIBUTES[11..13]
+        raise_unless(HealthcheckEndpoint::Error::Configuration::HttpStatusFailure, method, *validator_http_status_failure(value))
+      end
+    end
+
+    def validator_argument_type(method_name, argument)
+      [
+        argument,
+        argument.is_a?(
+          case method_name
+          when :services then ::Hash
+          when *HealthcheckEndpoint::Configuration::ATTRIBUTES[1..3] then ::Array
+          when *HealthcheckEndpoint::Configuration::ATTRIBUTES[4..7] then ::String
+          when *HealthcheckEndpoint::Configuration::ATTRIBUTES[8..13] then ::Integer
+          end
+        )
+      ]
+    end
+
+    def validator_endpoint(argument)
+      [argument, argument[%r{\A/.*\z}]]
+    end
+
+    def validator_http_status_success(argument)
+      [argument, HealthcheckEndpoint::Configuration::AVILABLE_HTTP_STATUSES_SUCCESS.include?(argument)]
+    end
+
+    def validator_http_status_failure(argument)
+      [argument, HealthcheckEndpoint::Configuration::AVILABLE_HTTP_STATUSES_FAILURE.include?(argument)]
+    end
+
+    def validator_services_callable(services_to_check, target_service = nil)
+      result = services_to_check.all? do |service_name, service_context|
+        target_service = service_name
+        service_context.respond_to?(:call)
+      end
+
+      [target_service, result]
+    end
+
+    def validator_services_conformity(services_to_check, target_service = nil)
+      result = services_to_check.all? do |service_name|
+        target_service = service_name
+        services.key?(service_name)
+      end
+
+      [target_service, result]
+    end
+
+    def raise_unless(exception_class, argument_name, argument_context, condition)
+      raise exception_class.new(argument_context, argument_name) unless condition
+    end
+  end
+end

data/lib/healthcheck_endpoint/core.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module HealthcheckEndpoint
+  module Error
+    module Configuration
+      require_relative 'error/configuration/argument_type'
+      require_relative 'error/configuration/unknown_service'
+      require_relative 'error/configuration/not_callable_service'
+      require_relative 'error/configuration/enpoint_pattern'
+      require_relative 'error/configuration/http_status_success'
+      require_relative 'error/configuration/http_status_failure'
+      require_relative 'error/configuration/not_configured'
+    end
+  end
+
+  require_relative 'version'
+  require_relative 'configuration'
+  require_relative 'resolver'
+  require_relative 'rack_middleware'
+end

data/lib/healthcheck_endpoint/error/configuration/argument_type.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module HealthcheckEndpoint
+  module Error
+    module Configuration
+      ArgumentType = ::Class.new(::ArgumentError) do
+        def initialize(arg_value, arg_name)
+          super("#{arg_value} is not a valid #{arg_name}")
+        end
+      end
+    end
+  end
+end

data/lib/healthcheck_endpoint/error/configuration/enpoint_pattern.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module HealthcheckEndpoint
+  module Error
+    module Configuration
+      EnpointPattern = ::Class.new(::ArgumentError) do
+        def initialize(arg_value, arg_name)
+          super("#{arg_value} does not match a valid enpoint pattern for #{arg_name}")
+        end
+      end
+    end
+  end
+end

data/lib/healthcheck_endpoint/error/configuration/http_status_failure.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module HealthcheckEndpoint
+  module Error
+    module Configuration
+      HttpStatusFailure = ::Class.new(::ArgumentError) do
+        def initialize(arg_value, arg_name)
+          super("Status #{arg_value} is wrong HTTP failure status for #{arg_name}. It should be in the range 500-511")
+        end
+      end
+    end
+  end
+end

data/lib/healthcheck_endpoint/error/configuration/http_status_success.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module HealthcheckEndpoint
+  module Error
+    module Configuration
+      HttpStatusSuccess = ::Class.new(::ArgumentError) do
+        def initialize(arg_value, arg_name)
+          super("Status #{arg_value} is wrong HTTP successful status for #{arg_name}. It should be in the range 200-226")
+        end
+      end
+    end
+  end
+end

data/lib/healthcheck_endpoint/error/configuration/not_callable_service.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module HealthcheckEndpoint
+  module Error
+    module Configuration
+      NotCallableService = ::Class.new(::ArgumentError) do
+        def initialize(service_name, services_setter)
+          super("Service #{service_name} is not callable. All values for #{services_setter} should be a callable objects")
+        end
+      end
+    end
+  end
+end

data/lib/healthcheck_endpoint/error/configuration/not_configured.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module HealthcheckEndpoint
+  module Error
+    module Configuration
+      NotConfigured = ::Class.new(::RuntimeError) do
+        def initialize
+          super('The configuration is empty. Please use HealthcheckEndpoint.configure before')
+        end
+      end
+    end
+  end
+end

data/lib/healthcheck_endpoint/error/configuration/unknown_service.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module HealthcheckEndpoint
+  module Error
+    module Configuration
+      UnknownService = ::Class.new(::ArgumentError) do
+        def initialize(service_name, services_setter)
+          super("Unknown #{service_name} service name for #{services_setter}. You should define it in config.services firstly")
+        end
+      end
+    end
+  end
+end

data/lib/healthcheck_endpoint/rack_middleware.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module HealthcheckEndpoint
+  class RackMiddleware
+    def initialize(
+      app,
+      resolver = HealthcheckEndpoint::Resolver,
+      counfigured = !!HealthcheckEndpoint.configuration
+    )
+      @app = app
+      @resolver = resolver
+      @counfigured = counfigured
+    end
+
+    def call(env)
+      raise HealthcheckEndpoint::Error::Configuration::NotConfigured unless counfigured
+
+      resolver.call(env) || app.call(env)
+    end
+
+    private
+
+    attr_reader :app, :resolver, :counfigured
+  end
+end