smart_proxy_dhcp_kea_api 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60b69b716ae58881effcacb442e0357e0d92a2b30b4c5be29e24439e07c9e047
-  data.tar.gz: c698f7bdb99f3965eb1f7eb02afe908559b29c2145e3c8870b87038c3552c101
+  metadata.gz: 42b1eec7524d54aa43e9f202c85cb88a92fbfcdf3dbf91a42df43e20d000ac1c
+  data.tar.gz: 66ae862538c0fc90345eb7a32e487ef63ef536c37cac572a07adfff9d39bb978
 SHA512:
-  metadata.gz: bd83ca3c705b98af40b57b11b9d9d10386f43277a07884d537eda07f28ef433e3939aeb5d7ab90d351e0f1f429560ea642a9a8ce0b4a98eb60867cb037c6b1e5
-  data.tar.gz: e965386db272058aa1504d089cc69e3e39ada4610a2fe96ff4e2f1a2c5ee7632577430f781e0bffc16239f7243d94f5acb536ef0e6ebcefd0558541b080a018d
+  metadata.gz: 5cf2dfcf2d1b5b52efa98f274b9abd4d777b5b62182f048401040a01baf3f7c32e70cf38921d7e596090a993b684ac19748257e8e2d67d9f35479ef0cc6f823c
+  data.tar.gz: 1c54018b7438505c0d8de97337a0363435498c29682e93d7699ffacb2933e7f4af57037c52bbe180b6273066b2c48e6712b06bf3484a83902715e585931d656b

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_plugin.rb

@@ -23,8 +23,12 @@ module Proxy
 
         # Defines the default settings for this provider. These values are used if
         # they are not explicitly overridden in a user's settings file
+        # The `kea_api_username` and `kea_api_password` can be used to enable
+        # HTTP Basic Authentication if required by the Kea control agent.
         # (e.g. `/etc/foreman-proxy/settings.d/dhcp_kea_api.yml`).
         default_settings kea_api_url: 'http://127.0.0.1:8000/',
+                         kea_api_username: nil,
+                         kea_api_password: nil,
                          blacklist_duration_minutes: 5,
                          open_timeout: 5,
                          read_timeout: 10

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_subnet_service.rb

@@ -31,7 +31,7 @@ module Proxy
         # @param reservations_by_ip [Proxy::MemoryStore] A memory store for reservations, passed to the parent class.
         # @param reservations_by_mac [Proxy::MemoryStore] A memory store for reservations, passed to the parent class.
         # @param reservations_by_name [Proxy::MemoryStore] A memory store for reservations, passed to the parent class.
-
+        # @return [void]
         # rubocop:disable Metrics/ParameterLists
         def initialize(client, leases_by_ip, leases_by_mac, reservations_by_ip, reservations_by_mac, reservations_by_name)
           @client = client
@@ -47,6 +47,8 @@ module Proxy
         #
         # @return [true] on success.
         # @raise [Proxy::DHCP::Error] if any part of the loading process fails.
+        # @see #load_subnets_and_reservations_from_kea
+        # @see #load_leases_from_kea
         # rubocop:disable Naming/PredicateMethod
         def load!
           subnets.clear
@@ -60,6 +62,9 @@ module Proxy
 
         # Fetches all subnets and their associated reservations from the Kea API.
         # This single `config-get` call is the most efficient way to get all static configuration.
+        # @return [void]
+        # @raise [Proxy::DHCP::Error] if the API call fails.
+        # @raise [IPAddr::InvalidAddressError] if a subnet address from Kea is invalid.
         # @see Proxy::DHCP::KeaApi::Client#post_command
         def load_subnets_and_reservations_from_kea
           config = @client.post_command('dhcp4', 'config-get')
@@ -80,6 +85,8 @@ module Proxy
         end
 
         # Fetches all active leases from the Kea API for the subnets currently in the cache.
+        # @return [void]
+        # @raise [Proxy::DHCP::Error] if the API call fails.
         # @see Proxy::DHCP::KeaApi::Client#post_command
         def load_leases_from_kea
           # This guard is necessary because the `lease4-get-all` command requires
@@ -114,6 +121,8 @@ module Proxy
         # Foreman Subnet and Reservation objects, and adds them to the cache.
         #
         # @param subnet_data [Hash] The hash representing a single subnet from Kea's `config-get` response.
+        # @return [void]
+        # @raise [IPAddr::InvalidAddressError] if the subnet string is not a valid IP address.
         def process_subnet(subnet_data)
           ip_object = IPAddr.new(subnet_data['subnet'])
           subnet_addr = ip_object.to_s
@@ -142,6 +151,7 @@ module Proxy
         #
         # @param subnet_data [Hash] The hash representing a single subnet.
         # @return [Array<String>, nil] An array of router IP addresses, or nil if none are found.
+        # @note The router data in Kea is a single comma-separated string which must be split into an array.
         def extract_routers(subnet_data)
           # The router data is a comma-separated string which must be split into an array.
           subnet_data['option-data']&.find { |opt| opt['name'] == 'routers' }&.[]('data')&.split(',')
@@ -151,6 +161,7 @@ module Proxy
         #
         # @param subnet_data [Hash] The hash representing a single subnet.
         # @return [Array<String>, nil] A two-element array containing the start and end of the range, or nil.
+        # @note The pool range is a hyphen-separated string (e.g. "10.0.0.10-10.0.0.20").
         def extract_range(subnet_data)
           # The pool range is a hyphen-separated string (e.g. "10.0.0.10-10.0.0.20").
           pool_string = subnet_data.dig('pools', 0, 'pool')
@@ -161,6 +172,7 @@ module Proxy
         #
         # @param res_data [Hash] The hash representing a single reservation.
         # @param subnet [Proxy::DHCP::Subnet] The subnet object this reservation belongs to.
+        # @return [void]
         def process_reservation(res_data, subnet)
           record = ::Proxy::DHCP::Reservation.new(res_data['hostname'], res_data['ip-address'], res_data['hw-address'], subnet)
           # Add the reservation to the parent class's cache, making it searchable.

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_version.rb

@@ -3,7 +3,8 @@
 module Proxy
   module DHCP
     module KeaApi
-      VERSION = '1.0.1'
+      # The current version of the smart_proxy_dhcp_kea_api gem.
+      VERSION = '1.1.0'
     end
   end
 end

data/lib/smart_proxy_dhcp_kea_api/kea_api_client.rb

@@ -16,6 +16,8 @@ module Proxy
         # Initialises a new Kea API client.
         #
         # @param url [String] The base URL of the Kea API endpoint (e.g. 'http://127.0.0.1:8000/').
+        # @param username [String, nil] The username for HTTP Basic Authentication.
+        # @param password [String, nil] The password for HTTP Basic Authentication.
         # @param open_timeout [Integer] Time in seconds to wait for the initial TCP connection to be established (defaults to 5).
         # @param read_timeout [Integer] Time in seconds to wait for a response from the server after the connection is made (defaults to 10).
         # @raise [ArgumentError] if the URL is blank, malformed, or not a valid HTTP/S URL.
@@ -26,10 +28,12 @@ module Proxy
         # @example Initialization with Custom Timeouts
         #   client = Proxy::DHCP::KeaApi::Client.new(
         #     url: 'http://127.0.0.1:8000',
+        #     username: 'myuser',
+        #     password: 'mypassword'
         #     open_timeout: 2,
         #     read_timeout: 5
         #   )
-        def initialize(url:, open_timeout: 5, read_timeout: 10)
+        def initialize(url:, username: nil, password: nil, open_timeout: 5, read_timeout: 10)
           raise ArgumentError, 'Kea API URL cannot be nil or empty' if url.to_s.empty?
 
           @uri = URI.parse(url)
@@ -38,6 +42,8 @@ module Proxy
 
           raise ArgumentError, "Invalid Kea API URL: '#{url}' is missing a host" unless @uri.host
 
+          @username = username
+          @password = password
           @open_timeout = open_timeout
           @read_timeout = read_timeout
           logger.info "Initializing Kea API client for URL: #{@uri} with timeouts (open: #{@open_timeout}s, read: #{@read_timeout}s)"
@@ -49,9 +55,10 @@ module Proxy
         # @param service [String] The Kea service to target (e.g. 'dhcp4').
         # @param command [String] The command to execute (e.g. 'config-get', 'reservation-add').
         # @param arguments [Hash] A hash of arguments required by the command. Defaults to an empty hash.
-        #
         # @return [Hash] The 'arguments' hash from the Kea API response on success.
         # @raise [Proxy::DHCP::Error] if the API returns an error or if there's a communication issue.
+        #   This can be caused by underlying errors like `Net::ReadTimeout`, `Net::OpenTimeout`,
+        #   `Errno::ECONNREFUSED`, or `JSON::ParserError`.
         #
         # @example Get the current DHCPv4 configuration
         #   client = Proxy::DHCP::KeaApi::Client.new(url: 'http://localhost:8000')
@@ -69,6 +76,9 @@ module Proxy
         #     }
         #   })
         #   # => {"text"=>"Reservation added successfully."}
+        #
+        # @see https://kea.readthedocs.io/en/latest/api.html General Kea Management API documentation.
+        # @see https://kea.readthedocs.io/en/latest/api.html#ref-reservation-add For the `reservation-add` command.
         def post_command(service, command, arguments = {})
           header = { 'Content-Type' => 'application/json' }
           payload = {
@@ -87,16 +97,16 @@ module Proxy
           http.read_timeout = @read_timeout
           request = Net::HTTP::Post.new(@uri.request_uri, header)
           request.body = payload.to_json
+          request.basic_auth(@username, @password) if @username && @password
 
           logger.debug "Sending command to Kea: #{payload.inspect}"
           response = http.request(request)
 
           handle_response(response, command)
-          # This rescue block catches all standard communication errors (e.g. connection refused,
-          # timeouts, DNS failures) and wraps them in a Foreman-specific error type. This ensures
-          # consistent error handling and reporting up to the Foreman UI.
-        rescue StandardError => e
-          logger.error "Failed to send command to Kea API: #{e.message}"
+          # This rescue block catches specific, expected network and parsing errors,
+          # wrapping them in a Foreman-specific error type for consistent handling.
+        rescue Net::ReadTimeout, Net::OpenTimeout, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, JSON::ParserError => e
+          logger.error "Failed to send command to Kea API: #{e.class.name} - #{e.message}"
           raise Proxy::DHCP::Error, "Kea API communication error: #{e.message}"
         end
 
@@ -106,9 +116,9 @@ module Proxy
         #
         # @param response [Net::HTTPResponse] The raw response object from the HTTP request.
         # @param command [String] The original command that was sent, used for context-specific handling.
-        #
         # @return [Hash] The 'arguments' hash from the response on success.
-        # @raise [Proxy::DHCP::Error] if the response indicates a failure or is malformed.
+        # @raise [Proxy::DHCP::Error] if the response indicates a failure, is malformed, or is empty.
+        # @raise [JSON::ParserError] if the response body is not valid JSON.
         # @private
         def handle_response(response, command)
           body = JSON.parse(response.body)
@@ -119,7 +129,7 @@ module Proxy
 
           # If the response is successful, return its arguments. Otherwise, raise an error.
           if response_successful?(result, command)
-            # Provide a fallback of '{}' to prevent returning nil if 'arguments' key is missing.
+            # Provide a fallback of '{}' to prevent returning nil if the 'arguments' key is missing.
             result['arguments'] || {}
           else
             error_message = result['text'] || 'Unknown error from Kea API'
@@ -131,16 +141,16 @@ module Proxy
         #
         # @param result [Hash] The parsed result hash from the Kea response body.
         # @param command [String] The original command sent, needed for special case handling.
-        #
         # @return [Boolean] `true` if the response is considered a success, `false` otherwise.
+        #
+        # @see https://kea.readthedocs.io/en/stable/api.html For documentation on Kea API result codes.
         # @private
         def response_successful?(result, command)
           # Universal success is result code 0.
           return true if result['result'].zero?
-          # Special case: 'lease4-get-all' is successful even with result code 3 (no leases found).
-          return true if command == 'lease4-get-all' && result['result'] == 3
 
-          false
+          # Special case: 'lease4-get-all' is successful even with result code 3 (no leases found).
+          command == 'lease4-get-all' && result['result'] == 3
         end
       end
     end

data/lib/smart_proxy_dhcp_kea_api/plugin_configuration.rb

@@ -42,6 +42,8 @@ module Proxy
           container.singleton_dependency :kea_client, (lambda do
             ::Proxy::DHCP::KeaApi::Client.new(
               url: settings[:kea_api_url],
+              username: settings[:kea_api_username],
+              password: settings[:kea_api_password],
               open_timeout: settings[:open_timeout],
               read_timeout: settings[:read_timeout]
             )

data/lib/smart_proxy_dhcp_kea_api.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
+# The top-level namespace for the Foreman Smart Proxy application.
+# All core Smart Proxy modules and plugins are defined within this namespace.
 module Proxy
+  # The namespace for DHCP-related functionality within the Foreman Smart Proxy.
+  # All DHCP providers and their associated services are defined here.
   module DHCP
     # The top-level namespace for this DHCP provider. All classes, modules,
     # and services related to the Kea API integration will be defined within
     # this KeaApi module to prevent naming conflicts with other plugins.
+    # @see Proxy::DHCP::KeaApi::Client
+    # @see Proxy::DHCP::KeaApi::SubnetService
     module KeaApi; end
   end
 end

data/smart_proxy_dhcp_kea_api.gemspec

@@ -14,11 +14,25 @@ Gem::Specification.new do |s|
   s.description = 'Provides DHCP management for Foreman via the ISC Kea API, requiring the host_cmds and lease_cmds hooks.'
   s.license     = 'GPL-3.0-only'
   s.required_ruby_version = '>= 3.0', '< 4'
+  s.metadata = {
+    'bug_tracker_uri' => 'https://gitlab.surrey.ac.uk/sm0049/smart-proxy-dhcp-kea-api/-/issues',
+    'homepage_uri' => 'https://gitlab.surrey.ac.uk/sm0049/smart-proxy-dhcp-kea-api',
+    'rubygems_mfa_required' => 'true'
+  }
 
   s.files = Dir.glob('{lib}/**/*', File::FNM_DOTMATCH).reject { |f| File.directory?(f) }
   s.files += %w[LICENSE README.md smart_proxy_dhcp_kea_api.gemspec]
 
   s.require_paths = ['lib']
 
-  s.metadata['rubygems_mfa_required'] = 'true'
+  s.add_development_dependency "bundler"
+  s.add_development_dependency "concurrent-ruby"
+  s.add_development_dependency "rack-test"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "rubocop"
+  s.add_development_dependency "rubocop-rspec"
+  s.add_development_dependency "yard"
+  s.add_development_dependency "yard-rspec"
+  s.add_development_dependency "webmock"
 end

metadata

@@ -1,15 +1,155 @@
 --- !ruby/object:Gem::Specification
 name: smart_proxy_dhcp_kea_api
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Sam McCarthy
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-17 00:00:00.000000000 Z
-dependencies: []
+date: 2025-07-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Provides DHCP management for Foreman via the ISC Kea API, requiring the
   host_cmds and lease_cmds hooks.
 email:
@@ -19,6 +159,7 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- lib/.DS_Store
 - lib/smart_proxy_dhcp_kea_api.rb
 - lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_main.rb
 - lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_plugin.rb
@@ -31,6 +172,8 @@ homepage: https://gitlab.surrey.ac.uk/sm0049/smart-proxy-dhcp-kea-api
 licenses:
 - GPL-3.0-only
 metadata:
+  bug_tracker_uri: https://gitlab.surrey.ac.uk/sm0049/smart-proxy-dhcp-kea-api/-/issues
+  homepage_uri: https://gitlab.surrey.ac.uk/sm0049/smart-proxy-dhcp-kea-api
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []