smart_proxy_dhcp_kea_api 1.0.1 → 2.1.0

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_subnet_service.rb

@@ -18,11 +18,38 @@ module Proxy
       class SubnetService < ::Proxy::DHCP::SubnetService
         include Proxy::Log
 
-        # A hash mapping a subnet network address (e.g., "192.168.1.0") to its
-        # internal Kea API integer ID (e.g., 1). This is crucial for making
+        # Holds the data fetched during a reload before it is atomically swapped
+        # into the live cache. Wraps a throwaway parent SubnetService (for its
+        # thread-safe stores and lookup helpers) plus the Kea-specific maps, so
+        # the loaders can populate it exactly as they would the live object.
+        class Staging
+          attr_reader :service, :kea_id_map, :subnet_options
+
+          # @return [void]
+          def initialize
+            @service = ::Proxy::DHCP::SubnetService.initialized_instance
+            @kea_id_map = {}
+            @subnet_options = {}
+          end
+        end
+
+        # Maps Kea option-data names to their Foreman option keys and whether they are lists.
+        OPTION_MAP = {
+          'routers' => { key: :routers, list: true },
+          'domain-name-servers' => { key: :dns_servers, list: true },
+          'domain-name' => { key: :domain_name, list: false },
+          'ntp-servers' => { key: :ntp_servers, list: true }
+        }.freeze
+
+        # A hash mapping a subnet network address (e.g. "192.168.1.0") to its
+        # internal Kea API integer ID (e.g. 1). This is crucial for making
         # API calls that require a `subnet-id`.
         attr_reader :kea_id_map
 
+        # A hash mapping a subnet network address to its DHCP options hash.
+        # Used by the Provider to serve subnet-level options back to Foreman.
+        attr_reader :subnet_options
+
         # Initialises the SubnetService.
         #
         # @param client [Proxy::DHCP::KeaApi::Client] The client for communicating with the Kea API.
@@ -31,46 +58,91 @@ 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.
-
+        # @param cache_ttl [Integer] Number of seconds before the cache is considered stale (default: 60).
+        # @param managed_subnets [Array<String>, nil] List of CIDR networks to manage. Nil means manage all.
+        # @return [void]
         # rubocop:disable Metrics/ParameterLists
-        def initialize(client, leases_by_ip, leases_by_mac, reservations_by_ip, reservations_by_mac, reservations_by_name)
+        def initialize(client, leases_by_ip, leases_by_mac, reservations_by_ip, reservations_by_mac, reservations_by_name,
+                       cache_ttl: 60, managed_subnets: nil)
           @client = client
           @kea_id_map = {}
-          # The `super` call initialises the parent `DHCP::SubnetService`, setting up all the
-          # underlying data stores for caching subnets, leases, and reservations.
+          @subnet_options = {}
+          @cache_ttl = cache_ttl
+          @loaded_at = nil
+          @reload_mutex = Mutex.new
+          @managed_subnets = parse_managed_subnets(managed_subnets)
           super(leases_by_ip, leases_by_mac, reservations_by_ip, reservations_by_mac, reservations_by_name)
         end
         # rubocop:enable Metrics/ParameterLists
 
         # The main entry point for loading all DHCP data from the Kea server.
-        # It ensures the cache is cleared before performing a fresh load.
+        #
+        # All Kea API calls populate a fresh, off-to-the-side set of stores
+        # (`staging`); only once every fetch has succeeded are the new stores
+        # swapped into the live cache under the parent's monitor. This keeps the
+        # slow network fetch off the live cache so concurrent readers never see a
+        # half-populated state, and leaves the previous cache intact if the fetch
+        # fails partway through.
         #
         # @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
-          @kea_id_map.clear
+          staging = Staging.new
 
-          load_subnets_and_reservations_from_kea
-          load_leases_from_kea
+          load_subnets_and_reservations_from_kea(staging)
+          load_reservations_from_database(staging)
+          load_leases_from_kea(staging)
+
+          commit(staging)
           true
         end
         # rubocop:enable Naming/PredicateMethod
 
+        # Returns all subnets, refreshing the cache if stale.
+        #
+        # @return [Array<Proxy::DHCP::Subnet>] All cached subnets.
+        def all_subnets
+          reload_if_stale!
+          super
+        end
+
+        # Returns all host reservations, refreshing the cache if stale.
+        #
+        # @param subnet_address [String, nil] Optional subnet to filter by.
+        # @return [Array<Proxy::DHCP::Reservation>] All cached reservations.
+        def all_hosts(subnet_address = nil)
+          reload_if_stale!
+          super
+        end
+
+        # Returns all leases, refreshing the cache if stale.
+        #
+        # @param subnet_address [String, nil] Optional subnet to filter by.
+        # @return [Array<Proxy::DHCP::Lease>] All cached leases.
+        def all_leases(subnet_address = nil)
+          reload_if_stale!
+          super
+        end
+
         # 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.
+        #
+        # @param staging [Staging] The buffer to populate with fetched data.
+        # @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
+        def load_subnets_and_reservations_from_kea(staging)
           config = @client.post_command('dhcp4', 'config-get')
           subnets_data = config&.dig('Dhcp4', 'subnet4')
           return unless subnets_data
 
           subnets_data.each do |subnet_data|
-            process_subnet(subnet_data)
+            process_subnet(subnet_data, staging)
           end
-          # The rescue blocks ensure that if any API or parsing error occurs, the provider
-          # will fail to load, preventing the proxy from starting in a broken state.
         rescue Proxy::DHCP::Error => e
           logger.error "Failed to load subnets and reservations from Kea: #{e.message}"
           raise
@@ -79,29 +151,47 @@ module Proxy
           raise
         end
 
+        # Fetches dynamically added reservations from Kea's hosts-database via
+        # `reservation-get-all`. These are not included in `config-get` which only
+        # returns static reservations from the config file.
+        #
+        # @param staging [Staging] The buffer to populate with fetched data.
+        # @return [void]
+        def load_reservations_from_database(staging)
+          return if staging.kea_id_map.empty?
+
+          staging.kea_id_map.each do |network, subnet_id|
+            response = @client.post_command('dhcp4', 'reservation-get-all', { 'subnet-id': subnet_id })
+            hosts = response&.[]('hosts')
+            next unless hosts
+
+            subnet_obj = staging.service.find_subnet(network)
+            next unless subnet_obj
+
+            hosts.each do |res_data|
+              next if staging.service.find_host_by_mac(network, res_data['hw-address'])
+
+              process_reservation(res_data, subnet_obj, staging)
+            end
+          end
+        rescue Proxy::DHCP::Error => e
+          logger.debug "reservation-get-all not available or failed: #{e.message}"
+        end
+
         # Fetches all active leases from the Kea API for the subnets currently in the cache.
+        #
+        # @param staging [Staging] The buffer to populate with fetched data.
+        # @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
-          # a list of subnet IDs to query. If no subnets were loaded, we can't get leases.
-          return if @kea_id_map.empty?
+        def load_leases_from_kea(staging)
+          return if staging.kea_id_map.empty?
 
-          response = @client.post_command('dhcp4', 'lease4-get-all', { subnets: @kea_id_map.values })
+          response = @client.post_command('dhcp4', 'lease4-get-all', { subnets: staging.kea_id_map.values })
           return unless response && response['leases']
 
           response['leases'].each do |lease|
-            ip = lease['ip-address']
-            mac = lease['hw-address']
-            # We must find the corresponding Subnet object from our cache to associate with the lease.
-            subnet_obj = find_subnet(ip)
-            unless subnet_obj
-              logger.warn "Skipping lease for IP #{ip} as it does not belong to any known subnet."
-              next
-            end
-
-            record = ::Proxy::DHCP::Lease.new(nil, ip, mac, subnet_obj, lease['cltt'], lease['expire'], 'active')
-            # Add the lease to the parent class's cache.
-            add_lease(subnet_obj.network, record)
+            process_lease(lease, staging)
           end
         rescue Proxy::DHCP::Error => e
           logger.error "Failed to load all leases from Kea: #{e.message}"
@@ -110,32 +200,135 @@ module Proxy
 
         private
 
+        # Reloads the cache if it is older than the configured TTL. Only one thread
+        # performs the reload at a time (single-flight via `try_lock`); other threads
+        # that observe a stale cache serve the current snapshot instead of piling on
+        # duplicate, concurrent reloads.
+        #
+        # @return [void]
+        def reload_if_stale!
+          return unless stale?
+          return unless @reload_mutex.try_lock
+
+          begin
+            return unless stale? # re-check: another thread may have just reloaded
+
+            logger.debug "Cache TTL (#{@cache_ttl}s) expired, reloading from Kea"
+            load!
+          ensure
+            @reload_mutex.unlock
+          end
+        end
+
+        # Atomically replaces the live cache with the freshly-staged data. The swap
+        # runs under the parent's monitor so that readers (which take the same lock)
+        # observe either the entire old cache or the entire new one, never a mix.
+        #
+        # @param staging [Staging] The fully-populated buffer to promote.
+        # @return [void]
+        def commit(staging)
+          m.synchronize do
+            @subnets = staging.service.subnets
+            @leases_by_ip = staging.service.leases_by_ip
+            @leases_by_mac = staging.service.leases_by_mac
+            @reservations_by_ip = staging.service.reservations_by_ip
+            @reservations_by_mac = staging.service.reservations_by_mac
+            @reservations_by_name = staging.service.reservations_by_name
+            @kea_id_map = staging.kea_id_map
+            @subnet_options = staging.subnet_options
+            @loaded_at = Time.now
+          end
+        end
+
+        # Checks whether the cache has exceeded its TTL.
+        #
+        # @return [Boolean] true if the cache needs refreshing.
+        def stale?
+          return true unless @loaded_at
+
+          (Time.now - @loaded_at) > @cache_ttl
+        end
+
+        # Parses the managed_subnets setting into IPAddr objects for matching.
+        #
+        # @param managed_subnets [Array<String>, String, nil] CIDR networks to manage.
+        # @return [Array<IPAddr>, nil] Parsed networks, or nil to manage all.
+        def parse_managed_subnets(managed_subnets)
+          return nil if managed_subnets.nil?
+
+          subnets = Array(managed_subnets)
+          return nil if subnets.empty?
+
+          subnets.map { |cidr| IPAddr.new(cidr) }
+        end
+
+        # Checks whether a subnet should be managed by this proxy.
+        #
+        # @param subnet_addr [String] The network address of the subnet.
+        # @return [Boolean] true if the subnet should be managed.
+        def managed?(subnet_addr)
+          return true unless @managed_subnets
+
+          ip = IPAddr.new(subnet_addr)
+          # include? already returns true for an exact match (e.g. a /32 entry), so
+          # no separate equality check is needed.
+          @managed_subnets.any? { |network| network.include?(ip) }
+        end
+
         # Parses a single subnet hash from the API response, creates the necessary
         # 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.
-        def process_subnet(subnet_data)
+        # @param staging [Staging] The buffer to populate with the parsed subnet.
+        # @return [void]
+        # @raise [IPAddr::InvalidAddressError] if the subnet string is not a valid IP address.
+        def process_subnet(subnet_data, staging)
           ip_object = IPAddr.new(subnet_data['subnet'])
           subnet_addr = ip_object.to_s
-          # Correctly derive the netmask string from the IPAddr object's prefix
           mask = IPAddr.new('255.255.255.255').mask(ip_object.prefix).to_s
 
+          return unless managed?(subnet_addr)
+
           options = {
             routers: extract_routers(subnet_data),
             range: extract_range(subnet_data)
           }.compact
           subnet = ::Proxy::DHCP::Subnet.new(subnet_addr, mask, options)
 
-          # Add the parsed subnet to the parent class's in-memory cache.
-          add_subnet(subnet)
-          # Store the mapping between the network address and Kea's internal ID for future API calls.
-          @kea_id_map[subnet.network] = subnet_data['id']
+          staging.service.add_subnet(subnet)
+          staging.kea_id_map[subnet.network] = subnet_data['id']
+          staging.subnet_options[subnet.network] = extract_subnet_options(subnet_data)
           logger.info "Loaded subnet #{subnet.network}/#{subnet.netmask} and mapped to Kea ID #{subnet_data['id']}"
 
-          # The reservations are conveniently nested within each subnet object in the config.
           subnet_data['reservations']&.each do |res_data|
-            process_reservation(res_data, subnet)
+            process_reservation(res_data, subnet, staging)
+          end
+        end
+
+        # Extracts all DHCP options from a subnet into a normalised hash.
+        #
+        # @param subnet_data [Hash] The hash representing a single subnet.
+        # @return [Hash] A hash of option names to their values.
+        def extract_subnet_options(subnet_data)
+          opts = {}
+          option_data = subnet_data['option-data'] || []
+          option_data.each do |opt|
+            opts[opt['name']] = opt['data']
           end
+          opts['next-server'] = subnet_data['next-server'] if meaningful_boot_value?(subnet_data['next-server'])
+          opts['boot-file-name'] = subnet_data['boot-file-name'] if meaningful_boot_value?(subnet_data['boot-file-name'])
+          opts
+        end
+
+        # Returns true when a Kea boot field carries a real value. Kea reports an
+        # unset next-server as "0.0.0.0" and an unset boot-file-name as "", which
+        # are placeholders that must not be round-tripped back to Foreman as if a
+        # user had configured them (doing so triggers spurious DHCP rebuilds).
+        #
+        # @param value [String, nil] The raw value from Kea.
+        # @return [Boolean] true if the value is present and not a placeholder.
+        def meaningful_boot_value?(value)
+          !value.nil? && !value.to_s.strip.empty? && value != '0.0.0.0'
         end
 
         # Extracts and formats the router data from a subnet's options.
@@ -143,8 +336,9 @@ 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.
         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(',')
+          router_opt = subnet_data['option-data']&.find { |opt| opt['name'] == 'routers' }
+          data = router_opt&.[]('data')
+          data&.split(',')&.map(&:strip)
         end
 
         # Extracts the IP range from a subnet's first pool.
@@ -152,21 +346,71 @@ 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.
         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')
-          pool_string&.split('-')
+          pool_string&.split('-')&.map(&:strip)
         end
 
         # Creates a Foreman Reservation object from Kea data and adds it to the cache.
+        # Includes option-data, next-server, and boot-file-name so that Foreman can
+        # round-trip these values when querying existing reservations.
         #
         # @param res_data [Hash] The hash representing a single reservation.
         # @param subnet [Proxy::DHCP::Subnet] The subnet object this reservation belongs to.
-        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.
-          add_host(subnet.network, record)
+        # @param staging [Staging] The buffer to populate with the parsed reservation.
+        # @return [void]
+        def process_reservation(res_data, subnet, staging)
+          opts = extract_reservation_options(res_data)
+          record = ::Proxy::DHCP::Reservation.new(
+            res_data['hostname'], res_data['ip-address'], res_data['hw-address'], subnet, opts
+          )
+          staging.service.add_host(subnet.network, record)
           logger.debug "Loaded reservation for #{res_data['hw-address']} on subnet #{subnet.network}"
         end
+
+        # Extracts Foreman-compatible options from a Kea reservation hash.
+        #
+        # @param res_data [Hash] The reservation data from Kea's config-get.
+        # @return [Hash] Options hash suitable for Proxy::DHCP::Reservation.
+        def extract_reservation_options(res_data)
+          opts = {}
+          opts[:nextServer] = res_data['next-server'] if meaningful_boot_value?(res_data['next-server'])
+          opts[:filename] = res_data['boot-file-name'] if meaningful_boot_value?(res_data['boot-file-name'])
+          map_option_data(opts, res_data['option-data'] || [])
+          opts
+        end
+
+        # Applies Kea option-data entries to a Foreman options hash using OPTION_MAP.
+        #
+        # @param opts [Hash] The target options hash to populate.
+        # @param option_data [Array<Hash>] The option-data array from Kea.
+        # @return [void]
+        def map_option_data(opts, option_data)
+          option_data.each do |opt|
+            mapping = OPTION_MAP[opt['name']]
+            next unless mapping
+
+            data = opt['data']
+            opts[mapping[:key]] = mapping[:list] ? data&.split(',')&.map(&:strip) : data
+          end
+        end
+
+        # Creates a Foreman Lease object from Kea data and adds it to the cache.
+        #
+        # @param lease [Hash] The lease data from Kea's lease4-get-all response.
+        # @param staging [Staging] The buffer to populate with the parsed lease.
+        # @return [void]
+        def process_lease(lease, staging)
+          ip = lease['ip-address']
+          mac = lease['hw-address']
+          subnet_obj = staging.service.find_subnet(ip)
+          unless subnet_obj
+            logger.warn "Skipping lease for IP #{ip} as it does not belong to any known subnet."
+            return
+          end
+
+          record = ::Proxy::DHCP::Lease.new(nil, ip, mac, subnet_obj, lease['cltt'], lease['expire'], 'active')
+          staging.service.add_lease(subnet_obj.network, record)
+        end
       end
     end
   end

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 = '2.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.to_s) if @username
 
           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,18 @@ 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
+          result_code = result['result']
+          raise Proxy::DHCP::Error, "Kea API Error: Response missing 'result' field" if result_code.nil?
 
-          false
+          return true if result_code.zero?
+
+          # Special case: 'lease4-get-all' is successful even with result code 3 (no leases found).
+          command == 'lease4-get-all' && result_code == 3
         end
       end
     end

data/lib/smart_proxy_dhcp_kea_api/plugin_configuration.rb

@@ -28,20 +28,18 @@ module Proxy
         # @param settings [Hash] The settings hash for this provider.
 
         def load_dependency_injection_wirings(container, settings)
-          # A standard in-memory key-value store provided by the Smart Proxy framework.
-          # It's used by the SubnetService to cache DHCP data.
-          container.singleton_dependency :memory_store, -> { ::Proxy::MemoryStore.new }
-
           # A singleton service that manages the temporary blacklisting of suggested IP addresses
           # to prevent race conditions. Its duration is configured via the settings file.
           container.singleton_dependency :unused_ips, -> { ::Proxy::DHCP::FreeIps.new(settings[:blacklist_duration_minutes]) }
 
           # The custom client for communicating with the Kea API. This is registered as a singleton
-          # so that a single, persistent HTTP connection pool is used for all API calls.
+          # so that a single client instance (with its configuration) is shared across all requests.
           # @see Proxy::DHCP::KeaApi::Client#initialize
           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]
             )
@@ -49,18 +47,19 @@ module Proxy
 
           # The custom service for caching all subnet, reservation, and lease data.
           # This is a singleton because we want one central, authoritative cache that all
-          # requests can share. It depends on the Kea client to fetch data and the memory
-          # stores to cache it.
+          # requests can share. Each store must be a separate instance to avoid collisions
+          # between leases and reservations keyed by the same IP/MAC.
           # @see Proxy::DHCP::KeaApi::SubnetService#initialize
           container.singleton_dependency :subnet_service, (lambda do
-            memory_store = container.get_dependency(:memory_store)
             ::Proxy::DHCP::KeaApi::SubnetService.new(
               container.get_dependency(:kea_client),
-              memory_store,
-              memory_store,
-              memory_store,
-              memory_store,
-              memory_store
+              ::Proxy::MemoryStore.new,
+              ::Proxy::MemoryStore.new,
+              ::Proxy::MemoryStore.new,
+              ::Proxy::MemoryStore.new,
+              ::Proxy::MemoryStore.new,
+              cache_ttl: settings[:cache_ttl],
+              managed_subnets: settings.fetch(:managed_subnets, nil)
             )
           end)
 
@@ -68,7 +67,7 @@ module Proxy
           # for handling DHCP requests from Foreman. It depends on the subnet service,
           # the API client, and the IP blacklist service to do its job.
           # @see Proxy::DHCP::KeaApi::Provider#initialize
-          container.dependency :dhcp_provider, (lambda do
+          container.singleton_dependency :dhcp_provider, (lambda do
             ::Proxy::DHCP::KeaApi::Provider.new(
               container.get_dependency(:subnet_service),
               container.get_dependency(:kea_client),

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