data_plane_api 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc317af5694ae9e6972ddbfd6db39c0389cd57c93fff4c76ac093ef6c5b9a1bd
-  data.tar.gz: 455464f49c2842dea2849e8d3c3fdaab3b74f879281e4ea36d122f18750cb746
+  metadata.gz: 7da2ff7eebc65e3bb292ae067777b6e55437e217a01b60655de59c5056276645
+  data.tar.gz: c5a9c0c7fb385cde8fb92a437c8c4f33d2c306d34b20209f0030633c9e1af574
 SHA512:
-  metadata.gz: 652ea631a623bff177c3f9b7d662be8915a3f79d4c95f296d9fe946bd4b481d63b758db425438c8293a261ccad316c56530ca55ab6a86e0420c294680dde2025
-  data.tar.gz: 1acc0677dbf9633846535f875ea3f2e2f97d589ffd1760ac2efc3c43aed7eedac3efadfdbdb68629a5b44d465e75db92dfa15cfd28f996e83e8b39c4fe7a59e2
+  metadata.gz: 68e4a6676388face3a521ad62036935b5d374897b153d308d2ef61146812990e80181d2d06661ba04e956bd18590d0d53869e902be76d0b63b579baf1c669143
+  data.tar.gz: '0941b0e0212dd52b012fea661aa7f127cc21babe82249969d70adca38f76704940802625c3fe97c51cbf67ec4afd58ebac92c289e3d0dcd6099e5abe95afaf17'

data/.rubocop.yml

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

data/.ruby-version

@@ -1 +1 @@
-3.1.3
+3.4.2

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-04-10
+
+### Added
+- Rewrite type annotations from YARD to sorbet (inline RBS)
+- Add mock mode `DataPlaneApi::Configuration#mock`
+
 ## [0.1.0] - 2022-12-26
 
 - Initial release

data/Gemfile

@@ -5,11 +5,14 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in data_plane_api.gemspec
 gemspec
 
-gem 'debug' # Ruby debugger
+gem 'byebug', '~> 12.0' # debugger
 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 'rubocop-sorbet', '~> 0.10.0' # Rubocop config for sorbet
 gem 'shoulda-context', '~> 2.0' # Testing utilities
-gem 'vcr' # Save HTTP interactions to files during tests
-gem 'webmock' # Mock network interactions
+gem 'sorbet', '~> 0.5' # static typechecker
+gem 'tapioca', '~> 0.16.11', require: false # RBI generator
+gem 'vcr', '~> 6.3.1' # Save HTTP interactions to files during tests
+gem 'webmock', '~> 3.25.1' # Mock network interactions

data/Gemfile.lock

@@ -1,78 +1,135 @@
 PATH
   remote: .
   specs:
-    data_plane_api (0.1.1)
+    data_plane_api (0.2.0)
+      booleans (~> 0.1.3)
       faraday (> 1, < 3)
+      sorbet-runtime (~> 0.5)
 
 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)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.3)
+    base64 (0.2.0)
+    benchmark (0.2.1)
+    bigdecimal (3.1.9)
+    booleans (0.1.3)
+      sorbet-runtime (>= 0.5)
+    byebug (12.0.0)
+    crack (1.0.0)
+      bigdecimal
       rexml
-    debug (1.7.0)
-      irb (>= 1.5.0)
-      reline (>= 0.3.1)
+    erubi (1.13.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)
+    hashdiff (1.1.2)
+    json (2.10.2)
+    language_server-protocol (3.17.0.4)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (5.25.5)
+    netrc (0.11.0)
+    parallel (1.26.3)
+    parser (3.3.7.4)
       ast (~> 2.4.1)
-    public_suffix (5.0.1)
+      racc
+    prism (1.4.0)
+    public_suffix (6.0.1)
+    racc (1.8.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)
+    rbi (0.3.1)
+      prism (~> 1.0)
+      rbs (>= 3.4.4)
+      sorbet-runtime (>= 0.5.9204)
+    rbs (3.9.2)
+      logger
+    regexp_parser (2.10.0)
+    rexml (3.4.1)
+    rubocop (1.75.2)
       json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
-      parser (>= 3.1.2.1)
+      parser (>= 3.3.0.2)
       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)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.44.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)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.44.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-espago (1.1.8)
       rubocop
-    ruby-progressbar (1.11.0)
+    rubocop-sorbet (0.10.0)
+      rubocop (>= 1)
+    ruby-progressbar (1.13.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)
+    sorbet (0.5.12003)
+      sorbet-static (= 0.5.12003)
+    sorbet-runtime (0.5.12003)
+    sorbet-static (0.5.12003-universal-darwin)
+    sorbet-static (0.5.12003-x86_64-linux)
+    sorbet-static-and-runtime (0.5.12003)
+      sorbet (= 0.5.12003)
+      sorbet-runtime (= 0.5.12003)
+    spoom (1.6.1)
+      erubi (>= 1.10.0)
+      prism (>= 0.28.0)
+      rbi (>= 0.2.3)
+      sorbet-static-and-runtime (>= 0.5.10187)
+      thor (>= 0.19.2)
+    tapioca (0.16.11)
+      benchmark
+      bundler (>= 2.2.25)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      rbi (~> 0.2)
+      sorbet-static-and-runtime (>= 0.5.11087)
+      spoom (>= 1.2.0)
+      thor (>= 1.2.0)
+      yard-sorbet
+    thor (1.2.1)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    vcr (6.3.1)
+      base64
+    webmock (3.25.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
+    yard-sorbet (0.9.0)
+      sorbet-runtime
+      yard
 
 PLATFORMS
   arm64-darwin-20
+  arm64-darwin-23
   x86_64-linux
 
 DEPENDENCIES
+  byebug (~> 12.0)
   data_plane_api!
-  debug
   minitest (~> 5.0)
   rake (~> 13.0)
   rubocop (~> 1.21)
   rubocop-espago (~> 1.0)
+  rubocop-sorbet (~> 0.10.0)
   shoulda-context (~> 2.0)
-  vcr
-  webmock
+  sorbet (~> 0.5)
+  tapioca (~> 0.16.11)
+  vcr (~> 6.3.1)
+  webmock (~> 3.25.1)
 
 BUNDLED WITH
-   2.4.1
+   2.6.7

data/README.md

@@ -1,11 +1,18 @@
 # DataPlaneApi Ruby
 
-This gem provides a simple interface for the Community Edition of the HAProxy DataPlane API.
+This gem provides a simple interface for the Community Edition of
+the HAProxy Data Plane 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.
 
+[HAProxy](https://www.haproxy.com/) is a load balancer.
+The [Data Plane API](https://www.haproxy.com/documentation/dataplaneapi/community/)
+can be used to manage your HAProxy config,
+backends and servers.
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/data_plane_api.gemspec

@@ -12,7 +12,7 @@ require_relative 'lib/data_plane_api/version'
   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.required_ruby_version = '>= 3.2.0'
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://github.com/espago/data_plane_api_ruby'
@@ -30,7 +30,9 @@ require_relative 'lib/data_plane_api/version'
   spec.require_paths = ['lib']
 
   # Uncomment to register a new dependency of your gem
+  spec.add_dependency 'booleans', '~> 0.1.3'
   spec.add_dependency 'faraday', '> 1', '< 3'
+  spec.add_dependency 'sorbet-runtime', '~> 0.5'
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

data/lib/data_plane_api/configuration.rb

@@ -1,34 +1,42 @@
+# typed: true
 # frozen_string_literal: true
 
+require 'booleans/kernel_extension'
 require 'faraday'
 require 'logger'
 
 module DataPlaneApi
   # Stores configuration options for the HAProxy Data Plane API.
   class Configuration
-    # @return [String, URI::Generic, nil]
+    #: String | URI::Generic | nil
     attr_writer :url
-    # @return [String, nil] Basic Auth username.
+    # Basic Auth username.
+    #: String?
     attr_writer :basic_user
-    # @return [String, nil] Basic Auth password.
+    # Basic Auth password.
+    #: String?
     attr_writer :basic_password
-    # @return [Logger, nil]
+    #: Logger?
     attr_writer :logger
-    # @return [Integer, nil]
+    #: Integer?
     attr_writer :timeout
-    # @return [Boolean] whether this object is used as a global store of settings
+    # Do not make HTTP requests, just log them
+    #
+    #: bool
+    attr_writer :mock
+    # Whether this object is used as a global store of settings
+    #
+    #: bool
     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]
+    # @param global: whether this object is used as a global store of settings
+    # @param basic_user: Basic Auth username.
+    # @param basic_password: Basic Auth password.
+    #: (String | URI::Generic | nil, bool, bool, String?, String?, Logger?, Integer?, Configuration?) -> void
     def initialize(
       url: nil,
       global: false,
+      mock: false,
       basic_user: nil,
       basic_password: nil,
       logger: nil,
@@ -37,12 +45,14 @@ module DataPlaneApi
     )
 
       @global = global
+      @mock = mock
       @url = url
       @basic_user = basic_user
       @basic_password = basic_password
       @logger = logger
       @timeout = timeout
       @parent = parent
+      @connection = nil
 
       return unless global
 
@@ -50,53 +60,67 @@ module DataPlaneApi
       @timeout ||= 10
     end
 
-    # @return [Faraday::Connection]
+    #: -> Faraday::Connection
     def connection
       @connection || build_connection
     end
 
-    # @return [void]
+    #: -> void
     def freeze
       @connection = build_connection
       super
     end
 
-    # @return [String, URI::Generic, nil]
+    #: -> (String | URI::Generic | nil)
     def url
       return @url if @global || @url
 
-      parent.url
+      parent&.url
     end
 
-    # @return [String, nil] Basic Auth username.
+    # Basic Auth username.
+    #: -> String?
     def basic_user
       return @basic_user if @global || @basic_user
 
-      parent.basic_user
+      parent&.basic_user
     end
 
-    # @return [String, nil] Basic Auth password.
+    # Basic Auth password.
+    #: -> String?
     def basic_password
       return @basic_password if @global || @basic_password
 
-      parent.basic_password
+      parent&.basic_password
     end
 
-    # @return [Logger, nil]
+    #: -> Logger?
     def logger
       return @logger if @global || @logger
 
-      parent.logger
+      parent&.logger
     end
 
-    # @return [Integer, nil]
+    #: -> Integer?
     def timeout
       return @timeout if @global || @timeout
 
-      parent.timeout
+      parent&.timeout
     end
 
-    # @return [self, nil]
+    #: -> bool?
+    def mock
+      return @mock if @global || @mock
+
+      parent&.mock
+    end
+
+    #: -> bool
+    def mock?
+      Boolean(mock)
+    end
+
+    #: -> Configuration?
     def parent
       return if @global
 
@@ -106,7 +130,7 @@ module DataPlaneApi
     private
 
     if ::Faraday::VERSION > '2'
-      # @return [Faraday::Connection]
+      #: -> Faraday::Connection
       def build_connection
         headers = { 'Content-Type' => 'application/json' }
 
@@ -119,7 +143,7 @@ module DataPlaneApi
     else
       # Faraday 1.x compatibility
 
-      # @return [Faraday::Connection]
+      #: -> Faraday::Connection
       def build_connection
         headers = { 'Content-Type' => 'application/json' }
 

data/lib/data_plane_api/server.rb

@@ -1,23 +1,20 @@
+# typed: true
 # 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]
+    ADMIN_STATES = T.let(::Set[:ready, :maint, :drain], T::Set[Symbol])
+    OPERATIONAL_STATES = T.let(::Set[:up, :down, :stopping], T::Set[Symbol])
 
     class << self
-      # @param backend [String] Name of the backend
-      # @param name [String, nil] Name of the server whose settings will be returned.
+      # @param backend: Name of the backend
+      # @param name: 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]
+      #: (String?, String?, Configuration?) -> Faraday::Response?
       def get_runtime_settings(backend:, name: nil, config: nil)
         config ||= CONFIG
         if backend.nil? || backend.empty?
@@ -31,11 +28,9 @@ module DataPlaneApi
         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]
+      # @param backend: Name of the backend
+      # @param name: Name of the server whose transient settings should be updated.
+      #: (String?, String?, Hash[top, top], Configuration?) -> Faraday::Response?
       def update_transient_settings(backend:, name:, settings:, config: nil)
         config ||= CONFIG
         if backend.nil? || backend.empty?
@@ -53,44 +48,44 @@ module DataPlaneApi
 
       private
 
-      # @param method [Symbol]
-      # @param path [String, Pathname]
-      # @param config [HaProxy::DataPlaneApi::Configuration]
-      # @yieldparam request [Faraday::Request]
-      # @return [Faraday::Response]
+      #: (Symbol, String | Pathname, Configuration) { (Faraday::Request) -> void } -> Faraday::Response?
       def send_request(method:, path:, config:, &block)
-        request = nil
-        response = config.connection.public_send(method, path) do |req|
+        request = T.let(nil, T.nilable(Faraday::Request))
+        conn = config.connection
+        response = conn.public_send(method, path) do |req|
           block.call(req)
           req.options.timeout = config.timeout
           request = req
+          break if config.mock?
         end
 
-        log_communication(request, response, logger: config.logger)
+        log_communication(
+          conn.build_url(path),
+          T.must(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:)
+      #: (String, Faraday::Request, Faraday::Response?, Logger?) -> void
+      def log_communication(url, request, response, logger:)
         request_hash = {
-          method: request.http_method,
-          url: response.env.url,
-          params: request.params,
+          method:  request.http_method,
+          url:     url,
+          params:  request.params,
           headers: request.headers,
-          body: request.body
+          body:    request.body,
         }
         response_hash = {
-          status: response.status,
-          body: response.body,
-          headers: response.headers
+          status:  response&.status,
+          body:    response&.body,
+          headers: response&.headers,
         }
 
-        logger.debug <<~REQ
-          HAProxy #{request.http_method.to_s.upcase} #{response.env.url}
+        logger&.debug <<~REQ
+          HAProxy #{request.http_method.to_s.upcase} #{url}
           -----REQUEST-----
           #{::JSON.pretty_generate request_hash}
           -----RESPONSE-----

data/lib/data_plane_api/version.rb

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

data/lib/data_plane_api.rb

@@ -1,5 +1,7 @@
+# typed: true
 # frozen_string_literal: true
 
+require 'sorbet-runtime'
 require_relative 'data_plane_api/version'
 require_relative 'data_plane_api/configuration'
 
@@ -8,12 +10,10 @@ require_relative 'data_plane_api/configuration'
 module DataPlaneApi
   class Error < ::StandardError; end
 
-  # @return [DataPlaneAPI]
   CONFIG = Configuration.new(global: true)
 
   class << self
-    # @yieldparam config [Configuration]
-    # @return [Configuration]
+    #: { (Configuration) -> void } -> Configuration
     def configure(&block)
       block.call(CONFIG)
       CONFIG