data_plane_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ef9b77e23457f82223d970f629f3a49cd9d014d842f63b5b09ed69426728dcf5
+  data.tar.gz: 2ddee17d5f8ca74c2c26a371aade290f8eed7318ef0ee4007a1d7bf5c5755250
+SHA512:
+  metadata.gz: 8bc942ceebb102d2fb5805b48df7468e0cfcafe33ff7ee3508f9aef3c5b1ed7704dbfa29199fb990d5de992b24868cb274bcb37082a29e52a07fcb72834a6065
+  data.tar.gz: fe7567a34f721e700674a8d0e4e156b0ed368d74897c08de38c150f0bfe5d8fbe399ae6efc9462c22175b0f447e5975f471bdd1f3b88a2f2ef499c03ed1f988e

data/.rubocop.yml

@@ -0,0 +1,5 @@
+inherit_gem:
+  rubocop-espago: rubocop.yml
+
+AllCops:
+  TargetRubyVersion: 2.7

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2022-12-26
+
+- Initial release

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in data_plane_api.gemspec
+gemspec
+
+gem 'minitest', '~> 5.0' # Tests framework
+gem 'rake', '~> 13.0' # Ruby automation tasks
+gem 'rubocop', '~> 1.21' # Ruby linter
+gem 'rubocop-espago', '~> 1.0' # Custom Ruby linter config
+gem 'shoulda-context', '~> 2.0' # Testing utilities
+gem 'debug' # Ruby debugger
+gem 'vcr' # Save HTTP interactions to files during tests
+gem 'webmock' # Mock network interactions

data/Gemfile.lock

@@ -0,0 +1,77 @@
+PATH
+  remote: .
+  specs:
+    data_plane_api (0.1.0)
+      faraday (~> 2.7)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.1)
+      public_suffix (>= 2.0.2, < 6.0)
+    ast (2.4.2)
+    crack (0.4.5)
+      rexml
+    debug (1.7.0)
+      irb (>= 1.5.0)
+      reline (>= 0.3.1)
+    faraday (2.7.2)
+      faraday-net_http (>= 2.0, < 3.1)
+      ruby2_keywords (>= 0.0.4)
+    faraday-net_http (3.0.2)
+    hashdiff (1.0.1)
+    io-console (0.6.0)
+    irb (1.6.1)
+      reline (>= 0.3.0)
+    json (2.6.3)
+    minitest (5.16.3)
+    parallel (1.22.1)
+    parser (3.1.3.0)
+      ast (~> 2.4.1)
+    public_suffix (5.0.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.1)
+    reline (0.3.2)
+      io-console (~> 0.5)
+    rexml (3.2.5)
+    rubocop (1.41.1)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.1.2.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.23.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.24.0)
+      parser (>= 3.1.1.0)
+    rubocop-espago (1.0.2)
+      rubocop
+    ruby-progressbar (1.11.0)
+    ruby2_keywords (0.0.5)
+    shoulda-context (2.0.0)
+    unicode-display_width (2.3.0)
+    vcr (6.1.0)
+    webmock (3.18.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  arm64-darwin-20
+
+DEPENDENCIES
+  data_plane_api!
+  debug
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  rubocop (~> 1.21)
+  rubocop-espago (~> 1.0)
+  shoulda-context (~> 2.0)
+  vcr
+  webmock
+
+BUNDLED WITH
+   2.4.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Espago
+
+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,210 @@
+# DataPlaneApi Ruby
+
+This gem provides a simple interface for the Community Edition of the HAProxy DataPlane API.
+Currently, it only supports a handful of requests that we needed.
+More may be added in the future.
+
+We encourage you to make Pull Requests with more API endpoints.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add data_plane_api
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install data_plane_api
+
+## Usage
+
+The main namespace/module of this gem is `DataPlaneApi`.
+
+We used [this documentation](https://www.haproxy.com/documentation/dataplaneapi/community/#get-/services/haproxy/configuration/acls) as the reference for implementing this gem.
+
+Each section of the HAProxy Data Plane API should have its own module under
+`DataPlaneApi`. Each endpoint is represented as a singleton method of this module.
+
+eg. `DataPlaneApi::Server.get_runtime_settings`.
+
+### Configuration
+
+In order to make requests, you need to configure
+the API URL, user and password.
+
+You can configure the gem globally.
+
+```rb
+DataPlaneApi.configure do |c|
+    # REQUIRED
+    c.url = 'http://example.com'
+    c.basic_user = 'api_user'
+    c.basic_password = 'api_password'
+    # OPTIONAL
+    c.timeout = 25 # request timeout in seconds
+    c.logger = Logger.new($stdout) # custom logger
+end
+```
+
+These settings will be used by default in
+all requests without local configuration
+objects.
+
+You can also create configuration objects
+and pass them as arguments to particular request
+method calls.
+
+```rb
+# create a config object
+config = DataPlaneApi::Configuration.new(
+    url: 'http://example.com',
+    basic_user: 'api_user'
+    basic_password: 'api_password'
+)
+
+# make a request
+response = DataPlaneApi::Server.get_runtime_settings(
+    backend: 'foo',
+    config: config # use the configuration object
+)
+```
+
+A configuration object like that may contain
+incomplete configuration data. Any missing
+options will be inherited from the global
+configuration object.
+
+For example, let's say, that you've got a global
+configuration like that.
+
+```rb
+DataPlaneApi.configure do |c|
+    c.url = 'http://example.com'
+    c.basic_user = 'api_user'
+    c.basic_password = 'api_password'
+    c.timeout = 25 # request timeout in seconds
+end
+```
+
+You want to change the timeout to 2 seconds
+for a single request. You can achieve it
+by creating a new config object which contains
+only the new data, that you want to change when
+compared to the global config. The rest will
+be inherited.
+
+```rb
+config = DataPlaneApi::Configuration.new(timeout: 2)
+config.timeout #=> 2
+config.url #=> 'http://example.com'
+config.basic_user #=> 'api_user'
+```
+
+### Response
+
+You will always get a `Faraday::Response` object as a return value
+from a request call.
+
+The response body will be parsed to Ruby structures (Hash, Array, Integer, etc.)
+
+You may want to look at the [documentation of the faraday gem](https://lostisland.github.io/faraday/usage/) for more
+details.
+
+### Server
+
+Server endpoints live under the `DataPlaneApi::Server` module.
+
+### Runtime settings
+
+[Return an array of runtime servers' settings](https://www.haproxy.com/documentation/dataplaneapi/community/#get-/services/haproxy/runtime/servers)
+
+You can get an array of runtime servers' settings like so.
+
+```rb
+# @type [Faraday::Response]
+response = DataPlaneApi::Server.get_runtime_settings(backend: 'my_backend_name')
+
+response.status #=> 200
+response.headers #=> {"server"=>"Fly/c375678 (2021-04-23)", "content-type"=> ...
+response.body #=> [{"address":"12.0.5.102","admin_state":"ready","id":"1","name":"foo_bar1","operational_state":"up","port":4512}]
+```
+
+[Return one server runtime settings](https://www.haproxy.com/documentation/dataplaneapi/community/#get-/services/haproxy/runtime/servers/-name-)
+
+You can provide the name of a particular server to get only its
+settings.
+
+```rb
+# @type [Faraday::Response]
+response = DataPlaneApi::Server.get_runtime_settings(backend: 'my_backend_name', name: 'my_server_name')
+
+response.status #=> 200
+response.headers #=> {"server"=>"Fly/c375678 (2021-04-23)", "content-type"=> ...
+response.body #=> [{"address":"12.0.5.102","admin_state":"ready","id":"1","name":"foo_bar1","operational_state":"up","port":4512}]
+```
+
+You can override the global config by providing a config object.
+
+```rb
+# create a config object
+config = DataPlaneApi::Configuration.new(timeout: 2)
+
+response = DataPlaneApi::Server.get_runtime_settings(
+    config: config # use the new config
+    backend: 'my_backend_name',
+    name: 'my_server_name'
+)
+```
+
+### Transient settings
+
+[Replace server transient settings](https://www.haproxy.com/documentation/dataplaneapi/community/#put-/services/haproxy/runtime/servers/-name-)
+
+You can replace server transient settings like so.
+
+```rb
+# @type [Faraday::Response]
+response = DataPlaneApi::Server.get_runtime_settings(
+    backend: 'my_backend_name',
+    name: 'my_server_name',
+    settings: {
+        admin_state: 'ready',
+        operational_state: 'up'
+    }
+)
+
+response.status #=> 200
+response.headers #=> {"server"=>"Fly/c375678 (2021-04-23)", "content-type"=> ...
+response.body #=> [{"address":"12.0.5.102","admin_state":"ready","id":"1","name":"foo_bar1","operational_state":"up","port":4512}]
+```
+
+You can override the global config by providing a config object.
+
+```rb
+# create a config object
+config = DataPlaneApi::Configuration.new(timeout: 2)
+
+response = DataPlaneApi::Server.get_runtime_settings(
+    config: config # use the new config
+    backend: 'my_backend_name',
+    name: 'my_server_name',
+    settings: {
+        admin_state: 'ready',
+        operational_state: 'up'
+    }
+)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/espago/data_plane_api_ruby.
+
+## 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,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+::Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = ::FileList['test/**/*_test.rb']
+end
+
+require 'rubocop/rake_task'
+
+::RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/data_plane_api.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'lib/data_plane_api/version'
+
+::Gem::Specification.new do |spec|
+  spec.name = 'data_plane_api'
+  spec.version = ::DataPlaneApi::VERSION
+  spec.authors = ['Mateusz Drewniak', 'Espago']
+  spec.email = ['m.drewniak@espago.com']
+
+  spec.summary = 'Ruby gem which covers a limited subset of the HAProxy Data Plane API.'
+  spec.description = 'Ruby gem which covers a limited subset of the HAProxy Data Plane API.'
+  spec.homepage = 'https://github.com/espago/data_plane_api_ruby'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 2.7.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/espago/data_plane_api_ruby'
+  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = ::Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| ::File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency 'faraday', '~> 2.7'
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/data_plane_api/configuration.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'logger'
+
+module DataPlaneApi
+  # Stores configuration options for the HAProxy Data Plane API.
+  class Configuration
+    # @return [String, URI::Generic, nil]
+    attr_writer :url
+    # @return [String, nil] Basic Auth username.
+    attr_writer :basic_user
+    # @return [String, nil] Basic Auth password.
+    attr_writer :basic_password
+    # @return [Logger, nil]
+    attr_writer :logger
+    # @return [Integer, nil]
+    attr_writer :timeout
+    # @return [Boolean] whether this object is used as a global store of settings
+    attr_reader :global
+
+    # @param url [String, nil]
+    # @param global [Boolean] whether this object is used as a global store of settings
+    # @param basic_user [String, nil] Basic Auth username.
+    # @param basic_password [String, nil] Basic Auth password.
+    # @param logger [Logger, nil]
+    # @param timeout [Integer, nil]
+    # @param parent [self, nil]
+    def initialize(
+      url: nil,
+      global: false,
+      basic_user: nil,
+      basic_password: nil,
+      logger: nil,
+      timeout: nil,
+      parent: nil
+    )
+
+      @global = global
+      @url = url
+      @basic_user = basic_user
+      @basic_password = basic_password
+      @logger = logger
+      @timeout = timeout
+      @parent = parent
+
+      return unless global
+
+      @logger ||= ::Logger.new($stdout)
+      @timeout ||= 10
+    end
+
+    # @return [Faraday::Connection]
+    def connection
+      @connection || build_connection
+    end
+
+    # @return [void]
+    def freeze
+      @connection = build_connection
+      super
+    end
+
+    # @return [String, URI::Generic, nil]
+    def url
+      return @url if @global || @url
+
+      parent.url
+    end
+
+    # @return [String, nil] Basic Auth username.
+    def basic_user
+      return @basic_user if @global || @basic_user
+
+      parent.basic_user
+    end
+
+    # @return [String, nil] Basic Auth password.
+    def basic_password
+      return @basic_password if @global || @basic_password
+
+      parent.basic_password
+    end
+
+    # @return [Logger, nil]
+    def logger
+      return @logger if @global || @logger
+
+      parent.logger
+    end
+
+    # @return [Integer, nil]
+    def timeout
+      return @timeout if @global || @timeout
+
+      parent.timeout
+    end
+
+    # @return [self, nil]
+    def parent
+      return if @global
+
+      @parent || CONFIG
+    end
+
+    private
+
+    # @return [Faraday::Connection]
+    def build_connection
+      headers = { 'Content-Type' => 'application/json' }
+
+      ::Faraday.new(url: "#{url}/v2/", headers: headers) do |f|
+        f.request :json
+        f.response :json
+        f.request :authorization, :basic, basic_user, basic_password
+      end
+    end
+  end
+end

data/lib/data_plane_api/server.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'set'
+
+module DataPlaneApi
+  # Wraps endpoints regarding HAProxy servers.
+  module Server
+    # @return [Set<Symbol>]
+    ADMIN_STATES = ::Set[:ready, :maint, :drain]
+    # @return [Set<Symbol>]
+    OPERATIONAL_STATES = ::Set[:up, :down, :stopping]
+
+    class << self
+      # @param backend [String] Name of the backend
+      # @param name [String, nil] Name of the server whose settings will be returned.
+      #   If `nil` then an array of settings of all servers under the passed `backend`
+      #   will be returned.
+      # @param config [HaProxy::DataPlaneApi::Configuration, nil]
+      # @return [Faraday::Response]
+      def get_runtime_settings(backend:, name: nil, config: nil)
+        config ||= CONFIG
+        if backend.nil? || backend.empty?
+          raise ::ArgumentError, "`backend` should be present but was `#{backend.inspect}`"
+        end
+
+        path = "services/haproxy/runtime/servers/#{name}".delete_suffix('/')
+
+        send_request(method: :get, path: path, config: config) do |req|
+          req.params[:backend] = backend
+        end
+      end
+
+      # @param backend [String] Name of the backend
+      # @param name [String, nil] Name of the server whose transient settings should be updated.
+      # @param settings [Hash]
+      # @param config [HaProxy::DataPlaneApi::Configuration, nil]
+      # @return [Faraday::Response]
+      def update_transient_settings(backend:, name:, settings:, config: nil)
+        config ||= CONFIG
+        if backend.nil? || backend.empty?
+          raise ::ArgumentError, "`backend` should be present but was `#{backend.inspect}`"
+        end
+        raise ::ArgumentError, "`name` should be present but was `#{name.inspect}`" if name.nil? || name.empty?
+
+        path = "services/haproxy/runtime/servers/#{name}"
+
+        send_request(method: :put, path: path, config: config) do |req|
+          req.params[:backend] = backend
+          req.body = settings
+        end
+      end
+
+      private
+
+      # @param method [Symbol]
+      # @param path [String, Pathname]
+      # @param config [HaProxy::DataPlaneApi::Configuration]
+      # @yieldparam request [Faraday::Request]
+      # @return [Faraday::Response]
+      def send_request(method:, path:, config:, &block)
+        request = nil
+        response = config.connection.public_send(method, path) do |req|
+          block.call(req)
+          req.options.timeout = config.timeout
+          request = req
+        end
+
+        log_communication(request, response, logger: config.logger)
+
+        response
+      end
+
+      # @param request [Faraday::Request]
+      # @param response [Faraday::Response]
+      # @param logger [Logger]
+      # @return [void]
+      def log_communication(request, response, logger:)
+        request_hash = {
+          method: request.http_method,
+          url: response.env.url,
+          params: request.params,
+          headers: request.headers,
+          body: request.body
+        }
+        response_hash = {
+          status: response.status,
+          body: response.body,
+          headers: response.headers
+        }
+
+        logger.debug <<~REQ
+          HAProxy #{request.http_method.to_s.upcase} #{response.env.url}
+          -----REQUEST-----
+          #{::JSON.pretty_generate request_hash}
+          -----RESPONSE-----
+          #{::JSON.pretty_generate response_hash}
+        REQ
+      end
+    end
+  end
+end

data/lib/data_plane_api/version.rb

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

data/lib/data_plane_api.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'data_plane_api/version'
+require_relative 'data_plane_api/configuration'
+
+# Contains code which implements a subset of the
+# HAProxy Data Plane API.
+module DataPlaneApi
+  class Error < ::StandardError; end
+
+  # @return [DataPlaneAPI]
+  CONFIG = Configuration.new(global: true)
+
+  class << self
+    # @yieldparam config [Configuration]
+    # @return [Configuration]
+    def configure(&block)
+      block.call(CONFIG)
+      CONFIG
+    end
+  end
+end
+
+require_relative 'data_plane_api/server'

data/sig/data_plane_api.rbs

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

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: data_plane_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mateusz Drewniak
+- Espago
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-12-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: Ruby gem which covers a limited subset of the HAProxy Data Plane API.
+email:
+- m.drewniak@espago.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- data_plane_api.gemspec
+- lib/data_plane_api.rb
+- lib/data_plane_api/configuration.rb
+- lib/data_plane_api/server.rb
+- lib/data_plane_api/version.rb
+- sig/data_plane_api.rbs
+homepage: https://github.com/espago/data_plane_api_ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/espago/data_plane_api_ruby
+  source_code_uri: https://github.com/espago/data_plane_api_ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Ruby gem which covers a limited subset of the HAProxy Data Plane API.
+test_files: []