on_strum-healthcheck 0.1.0

data/README.md

@@ -0,0 +1,224 @@
+# ![OnStrum::Healthcheck - Simple configurable application healthcheck rack middleware](https://repository-images.githubusercontent.com/769335579/9094eefe-bfc8-483d-9a65-e406d1eb92c6)
+
+[![Maintainability](https://api.codeclimate.com/v1/badges/b4dc21883d489d67fbef/maintainability)](https://codeclimate.com/github/on-strum/ruby-on-strum-healthcheck/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/b4dc21883d489d67fbef/test_coverage)](https://codeclimate.com/github/on-strum/ruby-on-strum-healthcheck/test_coverage)
+[![CircleCI](https://circleci.com/gh/on-strum/ruby-on-strum-healthcheck/tree/master.svg?style=svg)](https://circleci.com/gh/on-strum/ruby-on-strum-healthcheck/tree/master)
+[![Gem Version](https://badge.fury.io/rb/ruby_healthcheck.svg)](https://badge.fury.io/rb/ruby_healthcheck)
+[![Downloads](https://img.shields.io/gem/dt/ruby_healthcheck.svg?colorA=004d99&colorB=0073e6)](https://rubygems.org/gems/ruby_healthcheck)
+[![GitHub](https://img.shields.io/github/license/on-strum/ruby-on-strum-healthcheck)](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)
+  - [Rack](#rack)
+  - [Roda](#roda)
+  - [Hanami](#hanami)
+  - [Rails](#rails)
+- [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 'on_strum-healthcheck'
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+Or install it yourself as:
+
+```bash
+gem install on_strum-healthcheck
+```
+
+## Configuring
+
+To start working with this gem, you must configure it first as in the example below:
+
+```ruby
+# config/initializers/on_strum_healthcheck.rb
+
+require 'on_strum/healthcheck'
+
+OnStrum::Healthcheck.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 = {
+    postges: -> { 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[postges]
+
+  # 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[postges 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
+
+Please note, to start using this middleware you should configure `OnStrum::Healthcheck` before and then you should to add `OnStrum::Healthcheck::RackMiddleware` on the top of middlewares list.
+
+### Rack
+
+```ruby
+require 'rack'
+require 'on_strum/healthcheck'
+
+OnStrum::Healthcheck.configure
+
+RackCascade = Rack::Builder.app do
+  use OnStrum::Healthcheck::RackMiddleware
+  run YourApplication
+end
+```
+
+### Roda
+
+```ruby
+require 'roda'
+require 'on_strum/healthcheck'
+
+OnStrum::Healthcheck.configure
+
+class YourApplication < Roda
+  use OnStrum::Healthcheck::RackMiddleware
+end
+```
+
+### Hanami
+
+```ruby
+# config/initializers/on_strum_healthcheck.rb
+
+require 'on_strum/healthcheck'
+
+OnStrum::Healthcheck.configure
+
+# config/environment.rb
+
+Hanami.configure do
+  middleware.use MyRackMiddleware
+end
+```
+
+### Rails
+
+```ruby
+# config/initializers/on_strum_healthcheck.rb
+
+require 'on_strum/healthcheck'
+
+OnStrum::Healthcheck.configure
+
+# config/application.rb
+
+config.middleware.use OnStrum::Healthcheck::RackMiddleware
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/on-strum/ruby-on-strum-healthcheck>. 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/on-strum/ruby-on-strum-healthcheck/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 `on_strum-healthcheck` 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/on-strum/ruby-on-strum-healthcheck/graphs/contributors) for code and awesome suggestions
+- [The Stargazers](https://github.com/on-strum/ruby-on-strum-healthcheck/stargazers) for showing their support
+
+## Versioning
+
+`on_strum-healthcheck` 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 'on_strum/healthcheck'
+
+# 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/lib/on_strum/healthcheck/configuration.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module OnStrum
+  module Healthcheck
+    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(*OnStrum::Healthcheck::Configuration::ATTRIBUTES, keyword_init: true) do
+        def update(&block)
+          return self unless block
+
+          tap(&block)
+        end
+      end
+
+      attr_reader(*OnStrum::Healthcheck::Configuration::ATTRIBUTES)
+
+      def initialize(&block)
+        configuration_settings = build_configuration_settings(&block)
+        OnStrum::Healthcheck::Configuration::ATTRIBUTES.each do |attribute|
+          public_send(:"#{attribute}=", configuration_settings.public_send(attribute))
+        end
+      end
+
+      OnStrum::Healthcheck::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
+        OnStrum::Healthcheck::Configuration::Settings.new(
+          services: {},
+          services_startup: [],
+          services_liveness: [],
+          services_readiness: [],
+          endpoints_namespace: OnStrum::Healthcheck::Configuration::ENDPOINTS_NAMESPACE,
+          endpoint_startup: OnStrum::Healthcheck::Configuration::ENDPOINT_STARTUP,
+          endpoint_liveness: OnStrum::Healthcheck::Configuration::ENDPOINT_LIVENESS,
+          endpoint_readiness: OnStrum::Healthcheck::Configuration::ENDPOINT_READINESS,
+          endpoint_startup_status_success: OnStrum::Healthcheck::Configuration::DEFAULT_HTTP_STATUS_SUCCESS,
+          endpoint_liveness_status_success: OnStrum::Healthcheck::Configuration::DEFAULT_HTTP_STATUS_SUCCESS,
+          endpoint_readiness_status_success: OnStrum::Healthcheck::Configuration::DEFAULT_HTTP_STATUS_SUCCESS,
+          endpoint_startup_status_failure: OnStrum::Healthcheck::Configuration::DEFAULT_HTTP_STATUS_FAILURE,
+          endpoint_liveness_status_failure: OnStrum::Healthcheck::Configuration::DEFAULT_HTTP_STATUS_FAILURE,
+          endpoint_readiness_status_failure: OnStrum::Healthcheck::Configuration::DEFAULT_HTTP_STATUS_FAILURE
+        ).update(&block)
+      end
+
+      def validate_attribute(method, attribute, value) # rubocop:disable Metrics/AbcSize
+        raise_unless(OnStrum::Healthcheck::Error::Configuration::ArgumentType, method, *validator_argument_type(attribute, value))
+        case attribute
+        when OnStrum::Healthcheck::Configuration::ATTRIBUTES[0]
+          raise_unless(OnStrum::Healthcheck::Error::Configuration::NotCallableService, method, *validator_services_callable(value))
+        when *OnStrum::Healthcheck::Configuration::ATTRIBUTES[1..3]
+          raise_unless(OnStrum::Healthcheck::Error::Configuration::UnknownService, method, *validator_services_conformity(value))
+        when *OnStrum::Healthcheck::Configuration::ATTRIBUTES[4..7]
+          raise_unless(OnStrum::Healthcheck::Error::Configuration::EnpointPattern, method, *validator_endpoint(value))
+        when *OnStrum::Healthcheck::Configuration::ATTRIBUTES[8..10]
+          raise_unless(OnStrum::Healthcheck::Error::Configuration::HttpStatusSuccess, method, *validator_http_status_success(value))
+        when *OnStrum::Healthcheck::Configuration::ATTRIBUTES[11..13]
+          raise_unless(OnStrum::Healthcheck::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 *OnStrum::Healthcheck::Configuration::ATTRIBUTES[1..3] then ::Array
+            when *OnStrum::Healthcheck::Configuration::ATTRIBUTES[4..7] then ::String
+            when *OnStrum::Healthcheck::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, OnStrum::Healthcheck::Configuration::AVILABLE_HTTP_STATUSES_SUCCESS.include?(argument)]
+      end
+
+      def validator_http_status_failure(argument)
+        [argument, OnStrum::Healthcheck::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
+end

data/lib/on_strum/healthcheck/core.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OnStrum
+  module Healthcheck
+    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
+end

data/lib/on_strum/healthcheck/error/configuration/argument_type.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OnStrum
+  module Healthcheck
+    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
+end

data/lib/on_strum/healthcheck/error/configuration/enpoint_pattern.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OnStrum
+  module Healthcheck
+    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
+end

data/lib/on_strum/healthcheck/error/configuration/http_status_failure.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OnStrum
+  module Healthcheck
+    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
+end

data/lib/on_strum/healthcheck/error/configuration/http_status_success.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OnStrum
+  module Healthcheck
+    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
+end

data/lib/on_strum/healthcheck/error/configuration/not_callable_service.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OnStrum
+  module Healthcheck
+    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
+end

data/lib/on_strum/healthcheck/error/configuration/not_configured.rb

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

data/lib/on_strum/healthcheck/error/configuration/unknown_service.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module OnStrum
+  module Healthcheck
+    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
+end

data/lib/on_strum/healthcheck/rack_middleware.rb

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

data/lib/on_strum/healthcheck/resolver.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module OnStrum
+  module Healthcheck
+    class Resolver
+      require 'rack'
+      require 'securerandom'
+      require 'json'
+
+      PROBE_ENDPOINTS = %i[endpoint_startup endpoint_liveness endpoint_readiness].freeze
+      CONTENT_TYPE = { 'Content-Type' => 'application/json' }.freeze
+      JSONAPI_RESPONSE_TYPE = 'application-healthcheck'
+      ROOT_NAMESPACE = '/'
+
+      def self.call(rack_env)
+        new(rack_env).call
+      end
+
+      def initialize(rack_env)
+        @request = ::Rack::Request.new(rack_env)
+      end
+
+      def call
+        return unless probe_name
+
+        [response_status, OnStrum::Healthcheck::Resolver::CONTENT_TYPE, [response_jsonapi]]
+      end
+
+      private
+
+      attr_reader :request
+
+      def configuration
+        OnStrum::Healthcheck.configuration
+      end
+
+      def root_namespace
+        @root_namespace ||= configuration.endpoints_namespace
+      end
+
+      def root_namespace?
+        root_namespace.eql?(OnStrum::Healthcheck::Resolver::ROOT_NAMESPACE)
+      end
+
+      OnStrum::Healthcheck::Resolver::PROBE_ENDPOINTS.each do |method|
+        define_method(method) do
+          target_endpoint = configuration.public_send(method)
+          root_namespace? ? target_endpoint : "#{root_namespace}#{target_endpoint}"
+        end
+      end
+
+      def probe_name
+        @probe_name ||=
+          case request.path
+          when endpoint_startup then :startup
+          when endpoint_liveness then :liveness
+          when endpoint_readiness then :readiness
+          end
+      end
+
+      def probe_result
+        @probe_result ||=
+          configuration.public_send(:"services_#{probe_name}").each_with_object({}) do |service_name, response|
+            response[service_name] = configuration.services[service_name].call
+          end
+      end
+
+      def response_status
+        configuration.public_send(
+          probe_result.values.all? ? :"endpoint_#{probe_name}_status_success" : :"endpoint_#{probe_name}_status_failure"
+        )
+      end
+
+      def response_jsonapi
+        {
+          data: {
+            id: ::SecureRandom.uuid,
+            type: OnStrum::Healthcheck::Resolver::JSONAPI_RESPONSE_TYPE,
+            attributes: probe_result
+          }
+        }.to_json
+      end
+    end
+  end
+end

data/lib/on_strum/healthcheck/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OnStrum
+  module Healthcheck
+    VERSION = '0.1.0'
+  end
+end

data/lib/on_strum/healthcheck.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'healthcheck/core'
+
+module OnStrum
+  module Healthcheck
+    class << self
+      def configuration(&block)
+        @configuration ||= begin
+          return unless block
+
+          OnStrum::Healthcheck::Configuration.new(&block)
+        end
+      end
+
+      def configure(&block)
+        configuration(&block)
+      end
+
+      def reset_configuration!
+        @configuration = nil
+      end
+    end
+  end
+end