capistrano-data_plane_api 0.1.0

data/lib/capistrano/data_plane_api/helper.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Capistrano
+  module DataPlaneApi
+    # Provides helper methods
+    module Helper
+      # @return [Hash{String => Symbol}]
+      ADMIN_STATE_COLORS = {
+        'drain' => :on_blue,
+        'ready' => :on_green,
+        'maint' => :on_yellow
+      }.freeze
+
+      # @return [Hash{String => Symbol}]
+      OPERATIONAL_STATE_COLORS = {
+        'up' => :on_green,
+        'down' => :on_red,
+        'stopping' => :on_yellow
+      }.freeze
+
+      # @return [Boolean]
+      def no_haproxy?
+        !::ENV['NO_HAPROXY'].nil? && !::ENV['NO_HAPROXY'].empty?
+      end
+
+      # @return [Boolean]
+      def force_haproxy?
+        !::ENV['FORCE_HAPROXY'].nil? && !::ENV['FORCE_HAPROXY'].empty?
+      end
+
+      # @param state [String, Symbol, nil]
+      # @return [String, nil]
+      def humanize_admin_state(state)
+        return unless state
+
+        state = state.to_s
+        COLORS.decorate(" #{state.upcase} ", :bold, ADMIN_STATE_COLORS[state.downcase])
+      end
+
+      # @param state [String, Symbol, nil]
+      # @return [String, nil]
+      def humanize_operational_state(state)
+        return unless state
+
+        state = state.to_s
+        COLORS.decorate(" #{state.upcase} ", :bold, OPERATIONAL_STATE_COLORS[state.downcase])
+      end
+
+      # @param backend [Capistrano::DataPlaneApi::Configuration::Backend]
+      # @return [String]
+      def humanize_backend_name(backend)
+        COLORS.decorate(" #{backend.name} ", *backend.styles)
+      end
+    end
+  end
+end

data/lib/capistrano/data_plane_api/hooks.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative '../data_plane_api'
+
+after 'deploy:started', 'data_plane_api:server:set_drain'
+before 'deploy:publishing', 'data_plane_api:server:set_maint'
+after 'deploy:finished', 'data_plane_api:server:set_ready'

data/lib/capistrano/data_plane_api/show_state.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'pastel'
+require 'tty/box'
+require 'data_plane_api'
+
+module Capistrano
+  module DataPlaneApi
+    # Creates a human readable summary of the state of
+    # HAProxy backends and servers to stdout.
+    module ShowState
+      class << self
+        # @return [String]
+        def call # rubocop:disable Metrics/MethodLength
+          pastel = ::Pastel.new
+          result = ::String.new
+
+          result << pastel.blue.bold('HAProxy State')
+          result << "\n"
+          result << pastel.bold.yellow(::Time.now.to_s)
+          result << "\n\n"
+          config = ::DataPlaneApi::Configuration.new.tap do |c|
+            c.logger = ::Logger.new($stdout)
+            c.logger.level = ::Logger::FATAL
+            c.timeout = 2
+          end
+
+          ::Capistrano::DataPlaneApi.configuration.backends.each do |backend|
+            result << ::TTY::Box.frame(title: { top_left: backend_name(backend) }) do
+              b = ::String.new
+              servers = ::Capistrano::DataPlaneApi.get_backend_servers_settings(backend.name, config: config).body
+              servers.each do |server|
+                operational_state = operational_state(server)
+                admin_state = admin_state(server)
+                b << ::TTY::Box.frame(title:  { top_left: server_name(server) }, border: :thick) do
+                  s = ::String.new
+                  s << "      admin_state: #{admin_state}\n"
+                  s << "operational_state: #{operational_state}\n"
+                  s
+                end
+              end
+              b
+
+            rescue Error, ::Faraday::ConnectionFailed, ::Faraday::TimeoutError
+              b << pastel.bold.bright_red('Unavailable!')
+              b << "\n"
+              b
+            end
+          end
+
+          result
+        end
+
+        private
+
+        # @param server [Hash{String => Object}]
+        # @return [String]
+        def operational_state(server)
+          ::Capistrano::DataPlaneApi.humanize_operational_state(server['operational_state'])
+        end
+
+        # @param server [Hash{String => Object}]
+        # @return [String]
+        def admin_state(server)
+          ::Capistrano::DataPlaneApi.humanize_admin_state(server['admin_state'])
+        end
+
+        # @param server [Hash{String => Object}]
+        # @return [String]
+        def server_name(server)
+          pastel = ::Pastel.new
+          pastel.bold server['name']
+        end
+
+        # @param backend [Capistrano::DataPlaneApi::Configuration::Backend]
+        # @return [String]
+        def backend_name(backend)
+          pastel = ::Pastel.new
+          pastel.decorate(" #{backend.name} ", *backend.styles)
+        end
+
+      end
+
+    end
+  end
+end

data/lib/capistrano/data_plane_api/tasks.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'rake'
+
+namespace :data_plane_api do
+  namespace :server do
+    desc "Set the server's admin state to DRAIN through the HAProxy Data Plane API"
+    task :set_drain do
+      next if no_haproxy?
+
+      ::Capistrano::DataPlaneApi.server_set_drain fetch(:stage), force: force_haproxy?
+    end
+
+    desc "Set the server's admin state to READY through the HAProxy Data Plane API"
+    task :set_ready do
+      next if no_haproxy?
+
+      sleep 3
+      ::Capistrano::DataPlaneApi.server_set_ready fetch(:stage)
+    end
+
+    desc "Set the server's admin state to MAINT through the HAProxy Data Plane API"
+    task :set_maint do
+      next if no_haproxy?
+
+      sleep 3
+      ::Capistrano::DataPlaneApi.server_set_maint fetch(:stage), force: true
+    end
+  end
+end

data/lib/capistrano/data_plane_api/terminal_print_loop.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'tty/cursor'
+
+module Capistrano
+  module DataPlaneApi
+    module TerminalPrintLoop
+      class << self
+        # Calls the passed block in an endless loop with a given interval
+        # between calls.
+        # It prints the `String` returned from the block and clears it
+        # before another frame is printed.
+        #
+        # @yieldparam content [String]
+        # @param interval [Integer] Number of seconds between each screen refresh
+        def call(interval: 2)
+          previous_line_count = 0
+          previous_max_line_length = 0
+          loop do
+            content = ::String.new
+            yielded = yield(content)
+
+            print ::TTY::Cursor.clear_lines(previous_line_count + 1)
+
+            content = yielded if yielded.is_a?(::String) && content.length.zero?
+            line_count = 0
+            max_line_length = 0
+            content.each_line do |line|
+              line_count += 1
+              max_line_length = line.length if line.length > max_line_length
+            end
+            previous_line_count = line_count
+            previous_max_line_length = max_line_length
+
+            puts(content)
+            sleep(interval)
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/capistrano/data_plane_api/type.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'shale'
+
+require_relative 'diggable'
+require_relative 'equatable'
+
+module Capistrano
+  module DataPlaneApi
+    class Type < ::Shale::Mapper
+      include Diggable
+      include Equatable
+
+      alias to_h to_hash
+
+      # @param key [Symbol, String]
+      # @return [Object, nil]
+      def [](key)
+        public_send(key) if respond_to?(key)
+      end
+
+      # @param key [Symbol, String]
+      # @param val [Object]
+      def []=(key, val)
+        public_send(:"#{key}=", val)
+      end
+    end
+  end
+end

data/lib/capistrano/data_plane_api/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Capistrano
+  module DataPlaneApi
+    # @return [String]
+    VERSION = '0.1.0'
+  end
+end

data/lib/capistrano/data_plane_api.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require 'data_plane_api'
+require 'pastel'
+require 'pathname'
+require 'json'
+require 'logger'
+
+require_relative 'data_plane_api/version'
+require_relative 'data_plane_api/helper'
+require_relative 'data_plane_api/terminal_print_loop'
+require_relative 'data_plane_api/configuration'
+require_relative 'data_plane_api/show_state'
+
+module Capistrano
+  # Main module/namespace of the `capistrano-data_plane_api` gem.
+  module DataPlaneApi
+    extend Helper
+
+    class Error < ::StandardError; end
+    class NotConfiguredError < Error; end
+    class QueryError < Error; end
+    class NoOtherServerReadyError < Error; end
+    class UpdateServerStateError < Error; end
+    class NoSuchBackendError < Error; end
+    class NoBackendForThisStageError < Error; end
+
+    # @return [Pastel::Delegator]
+    COLORS = ::Pastel.new
+
+    class << self
+      # @return [Capistrano::DataPlaneApi::Configuration]
+      def configuration
+        raise NotConfiguredError, <<~ERR unless @configuration
+          `Capistrano::DataPlaneApi` is not configured!
+          You should register a configuration file like so:
+            Capistrano::DataPlaneApi.configuration = '/path/to/your/file.yaml'
+        ERR
+
+        @configuration
+      end
+
+      # @param val [Capistrano::DataPlaneApi::Configuration, Hash{String, Symbol => Object}, String, Pathname]
+      def configuration=(val)
+        case val
+        when ::Hash
+          # as of now `shale` does not support
+          # symbol keys in hashes, so
+          # we convert it to JSON an back
+          # to a Hash to convert all Symbols
+          # to Strings
+          @configuration = Configuration.from_json(val.to_json)
+        when Configuration
+          @configuration = val
+        when ::String, ::Pathname
+          @configuration = Configuration.from_file(val.to_s)
+          @configuration.file_path = val
+        else
+          raise ::ArgumentError,
+                "Configuration should be a `#{::Hash}`, `#{Configuration}`, #{::String} or #{::Pathname}" \
+                ", received: #{val.inspect} (#{val.class.inspect})"
+        end
+      end
+
+      # Prints the current configuration in a human readable format.
+      #
+      # @return [void]
+      def show_config
+        puts ::JSON.pretty_generate(configuration.to_h)
+      end
+
+      # Prints the current state of all backends and
+      # their servers in a human readable format.
+      #
+      # @return [void]
+      def show_state
+        TerminalPrintLoop.call do
+          ShowState.call
+        end
+      end
+
+      # Set server's admin_state to `drain`.
+      #
+      # @param deployment_stage [Symbol]
+      # @param force [Boolean] Change the server's state even when no other server is `up`
+      # @param config [::DataPlaneApi::Configuration, nil]
+      # @return [Hash, FalseClass] Server state after the change, or `false`
+      #   when no change happened
+      # @raise [Error] The process failed due to some reason
+      def server_set_drain(deployment_stage, force: false, config: nil)
+        haproxy_server, haproxy_backend = find_server_and_backend(deployment_stage)
+        return false if haproxy_backend.servers.length < 2 # skip HAProxy if there is only a single server
+
+        validate_backend_state(haproxy_backend, haproxy_server) unless force
+
+        conf = ::DataPlaneApi::Configuration.new(
+          basic_user: haproxy_backend.basic_user || @configuration.basic_user,
+          basic_password: haproxy_backend.basic_password || @configuration.basic_password,
+          parent: config,
+          url: configuration.api_url
+        )
+
+        # set the target server's state to `drain`
+        response =
+          ::DataPlaneApi::Server.update_transient_settings(
+            backend: haproxy_backend.name,
+            name: haproxy_server.name,
+            settings: { admin_state: :drain },
+            config: conf
+          )
+
+        unless response.status.between?(200, 299) && response.body['admin_state'] == 'drain'
+          raise UpdateServerStateError,
+                "HAProxy mutation failed! Couldn't set server's `admin_state` to `drain`."
+        end
+
+        response.body
+      end
+
+      # Set server's admin_state to `maint`.
+      #
+      # @param deployment_stage [Symbol]
+      # @param force [Boolean] Change the server's state even when no other server is `up`
+      # @param config [::DataPlaneApi::Configuration, nil]
+      # @return [Hash, FalseClass] Server state after the change, or `false`
+      #   when no change happened
+      # @raise [Error] The process failed due to some reason
+      def server_set_maint(deployment_stage, force: false, config: nil)
+        haproxy_server, haproxy_backend = find_server_and_backend(deployment_stage)
+        return false if haproxy_backend.servers.length < 2 # skip HAProxy if there is only a single server
+
+        validate_backend_state(haproxy_backend, haproxy_server) unless force
+
+        conf = ::DataPlaneApi::Configuration.new(
+          basic_user: haproxy_backend.basic_user || @configuration.basic_user,
+          basic_password: haproxy_backend.basic_password || @configuration.basic_password,
+          parent: config,
+          url: configuration.api_url
+        )
+
+        # set the target server's state to `maint`
+        response =
+          ::DataPlaneApi::Server.update_transient_settings(
+            backend: haproxy_backend.name,
+            name: haproxy_server.name,
+            settings: { admin_state: :maint },
+            config: conf
+          )
+
+        unless response.status.between?(200, 299) && response.body['admin_state'] == 'maint'
+          raise UpdateServerStateError,
+                "HAProxy mutation failed! Couldn't set server's `admin_state` to `drain`."
+        end
+
+        response.body
+      end
+
+      # Set server's admin_state to `ready`
+      #
+      # @param deployment_stage [Symbol]
+      # @param config [::DataPlaneApi::Configuration, nil]
+      # @return [Hash, FalseClass] Server state after the change, or `false`
+      #   when no change happened
+      # @raise [Error] The process failed due to some reason
+      def server_set_ready(deployment_stage, config: nil)
+        haproxy_server, haproxy_backend = find_server_and_backend(deployment_stage)
+        return false if haproxy_backend.servers.length < 2 # skip HAProxy if there is only a single server
+
+        conf = ::DataPlaneApi::Configuration.new(
+          basic_user: haproxy_backend.basic_user || @configuration.basic_user,
+          basic_password: haproxy_backend.basic_password || @configuration.basic_password,
+          parent: config,
+          url: configuration.api_url
+        )
+
+        # set the target server's state to `drain`
+        response =
+          ::DataPlaneApi::Server.update_transient_settings(
+            backend: haproxy_backend.name,
+            name: haproxy_server.name,
+            settings: { admin_state: :ready },
+            config: conf
+          )
+
+        unless response.status.between?(200, 299) &&
+               response.body['admin_state'] == 'ready' &&
+               response.body['operational_state'] == 'up'
+
+          raise UpdateServerStateError,
+                "HAProxy mutation failed! Couldn't set server's `admin_state` to `ready`."
+        end
+
+        response.body
+      end
+
+      # Find the HAProxy backend config with a particular name.
+      #
+      # @param backend_name [String]
+      # @return [Capistrano::DataPlaneApi::Configuration::Backend] HAProxy backend config.
+      # @raise [NoSuchBackendError] There is no backend with this name.
+      def find_backend(backend_name)
+        backend = configuration.backends.find { _1.name == backend_name }
+        if backend.nil?
+          raise NoSuchBackendError,
+                'There is no HAProxy backend with this name! ' \
+                "`#{backend_name.inspect}`"
+        end
+
+        backend
+      end
+
+      # Find the server and backend config for a particular
+      # deployment stage.
+      #
+      # @param deployment_stage [Symbol, String]
+      # @return [Capistrano::DataPlaneApi::Configuration::Server, Capistrano::DataPlaneApi::Configuration::Backend]
+      #   Two-element Array
+      #   where the first element is the HAProxy server config and the second one
+      #   is the HAProxy backend config
+      def find_server_and_backend(deployment_stage)
+        # @type [Capistrano::DataPlaneApi::Configuration::Server, nil]
+        haproxy_server = nil
+        deployment_stage_str = deployment_stage.to_s
+        # find the HAProxy backend that the
+        # current deployment target is a part of
+        # @type [Capistrano::DataPlaneApi::Configuration::Backend]
+        haproxy_backend =
+          configuration.backends.each do |backend|
+            haproxy_server = backend.servers.find { _1.stage == deployment_stage_str }
+            break backend if haproxy_server
+          end
+
+        unless haproxy_backend.is_a?(Configuration::Backend)
+          raise NoBackendForThisStageError,
+                'There are no HAProxy backends for this deployment stage! ' \
+                "#{deployment_stage.inspect} `#{configuration.file_path.inspect}`"
+        end
+
+        [haproxy_server, haproxy_backend]
+      end
+
+      # @param backend_name [String]
+      # @param config [::DataPlaneApi::Configuration, nil]
+      # @return [Faraday::Response]
+      def get_backend_servers_settings(backend_name, config: nil)
+        haproxy_backend = find_backend(backend_name)
+        conf = ::DataPlaneApi::Configuration.new(
+          basic_user: haproxy_backend.basic_user || @configuration.basic_user,
+          basic_password: haproxy_backend.basic_password || @configuration.basic_password,
+          parent: config,
+          url: configuration.api_url
+        )
+        response = ::DataPlaneApi::Server.get_runtime_settings(backend: backend_name, config: conf)
+        unless response.status.between?(200, 299)
+          raise QueryError,
+                "HAProxy query failed! Couldn't fetch servers' states"
+        end
+
+        response
+      end
+
+      private
+
+      # @param haproxy_backend [Capistrano::DataPlaneApi::Configuration::Backend]
+      # @param haproxy_server [Capistrano::DataPlaneApi::Configuration::Server]
+      # @return [void]
+      def validate_backend_state(haproxy_backend, haproxy_server)
+        response = get_backend_servers_settings(haproxy_backend.name)
+        unless haproxy_backend.servers.length == response.body.length
+          raise QueryError,
+                'HAProxy query failed! Configured servers for this backend' \
+                "don't match the configuration file! `#{configuration.file_path}`"
+        end
+
+        # @type [Array<Hash>]
+        server_statuses = response.body
+        # check if there are any servers other than this one that are `ready` and `up`
+        other_servers_ready = server_statuses.any? do |server_status|
+          server_status['admin_state'] == 'ready' &&
+            server_status['operational_state'] == 'up' &&
+            server_status['name'] != haproxy_server.name
+        end
+
+        unless other_servers_ready # rubocop:disable Style/GuardClause
+          raise NoOtherServerReadyError,
+                'No other server is `ready`' \
+                "in this backend `#{haproxy_backend.name}`"
+        end
+      end
+
+    end
+
+  end
+end
+
+require_relative 'data_plane_api/tasks' if defined?(::Rake)

data/sig/capistrano/data_plane_api.rbs

@@ -0,0 +1,6 @@
+module Capistrano
+  module DataPlaneApi
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

data/templates/bin/deploy

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+BIN_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+bundle exec ruby $BIN_DIR/deploy.rb $@

data/templates/bin/deploy.rb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require_relative '../config/data_plane_api'
+require 'capistrano/data_plane_api/deploy'
+
+::Capistrano::DataPlaneApi::Deploy.call

data/templates/config/data_plane_api.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'capistrano/data_plane_api'
+
+::Capistrano::DataPlaneApi.configuration =
+  ::File.expand_path('data_plane_api.yml', __dir__)

data/templates/config/data_plane_api.yml

@@ -0,0 +1,51 @@
+# We recommend to keep your credentials outside of Git.
+# You can achieve that by reading ENV variables using ERB in this file,
+# or add this file to .gitignore and provide an example file with fake data
+# called `config/data_plane_api.yml.example` which will serve as
+# an example of how it should be configured.
+
+# Root URL of the HAProxy Data Plane API
+api_url: http://example.com/haproxy-data-plane-api
+logger_level: <%= Logger::DEBUG %>
+# Default Data Plane API BasicAuth credentials
+basic_user: my_user # Data Plane API BasicAuth username
+basic_password: my_password # Data Plane API BasicAuth password
+
+# List of HAProxy backends
+backends:
+  - name: back_production # your HAProxy backend name
+    # styles defined in the `Pastel` gem, used in the terminal to uniquely identify this backend
+    # by coloring its name.
+    # Read more: https://github.com/piotrmurach/pastel#3-supported-colors
+    styles:
+      - :bold
+      - :on_red
+    # List of servers under this backend
+    servers:
+      - name: production1 # HAProxy server name and Capistrano stage name (config/deploy/production1.rb)
+      - name: production2
+      # when the HAProxy server name is different from the Capistrano stage name.
+      - name: production3_haproxy_server # HAProxy server name
+        stage: production3_capistrano_stage # Capistrano stage name (config/deploy/production3_capistrano_stage.rb)
+
+  - name: back_staging
+    styles:
+      - :bold
+      - :on_blue
+    # This backend has its own credentials
+    basic_user: some_other_user # Data Plane API BasicAuth user for this password
+    basic_password: some_other_password # Data Plane API BasicAuth password for this backend
+    servers:
+      - name: staging1
+      - name: staging2
+
+  - name: back_edge
+    styles:
+      - :bold
+      - :on_green
+    # You can use ERB to read data from Environment Variables.
+    basic_user: <%= ENV['USER'] %>
+    basic_password: <%= ENV['PASS'] %>
+    servers:
+      - name: edge1
+        stage: edge2