smart_proxy_dhcp_kea_api 1.0.0

data/README.md

@@ -0,0 +1,118 @@
+# Foreman Smart Proxy DHCP Kea API
+
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+A Foreman Smart Proxy plugin to provide DHCP management by interacting with the ISC Kea API. This provider allows Foreman to view subnets and leases and to create and delete host reservations directly via Kea's JSON-RPC interface.
+
+> [!NOTE]
+> This plugin currently supports **IPv4 only**.
+
+## Table of Contents
+
+[[_TOC_]]
+
+## Compatibility
+
+*   **Foreman Smart Proxy:**
+*   **ISC Kea:** 3.0.0 or newer
+
+## Features
+
+- Adds ISC Kea as a DHCP provider for Foreman.
+- Fetches subnet and pool information directly from the Kea API.
+- Fetches active lease information.
+- Provides host reservation management (add/delete).
+- Suggests the next available IP address from a subnet's pool.
+- Passes next-server and PXE boot file to Kea
+
+## Prerequisites
+
+- A running Foreman Smart Proxy instance.
+- A running ISC Kea DHCP server.
+- Network connectivity from the Smart Proxy server to the Kea server's API endpoint (default port 8000).
+
+> [!WARNING]
+> The Kea server **must** be configured with the **`host_cmds`** and **`lease_cmds`** hook libraries loaded for the `dhcp4` service. This plugin will not function without them.
+
+## Installation
+
+First, install the gem on your Foreman Smart Proxy server:
+
+```bash
+gem install smart_proxy_dhcp_kea_api
+```
+
+Add the gem to `/usr/share/foreman-proxy/bundler.d/Gemfile.local.rb`:
+
+```ruby
+gem 'smart_proxy_dhcp_kea_api'
+```
+
+After installing the gem or changing its configuration, you must restart the `foreman-proxy` service for the changes to take effect.
+ ```bash
+systemctl restart foreman-proxy
+ ```
+
+## Configuration
+
+Configuration is done in two files in the `/etc/foreman-proxy/settings.d/` directory.
+
+### 1. Enable the DHCP Module
+
+First, you must enable the main DHCP module and tell it to use this plugin as its provider.
+
+**File:** `/etc/foreman-proxy/settings.d/dhcp.yml`
+```yaml
+---
+:enabled: true
+:use_provider: dhcp_kea_api
+# It is highly recommended to enable the ping check for unused IPs to prevent conflicts.
+:ping_free_ip: true
+```
+
+### 2. Configure the Kea Provider
+
+Next, create a configuration file for the Kea provider itself.
+
+**File:** `/etc/foreman-proxy/settings.d/dhcp_kea_api.yml`
+
+This file enables the provider and contains all the settings needed to connect to your Kea API server.
+
+| Setting                    | Description                                                                  | Default                  | Required |
+| -------------------------- | ---------------------------------------------------------------------------- | ------------------------ | -------- |
+| `:enabled`                 | Enables or disables this provider module.                                    | `false`                  | **Yes**  |
+| `:kea_api_url`             | The full URL to your Kea API endpoint (HTTP or HTTPS).                       | `http://127.0.0.1:8000/` | **Yes**  |
+| `:open_timeout`            | Time in seconds to wait for the initial connection to be established.        | `5`                      | No       |
+| `:read_timeout`            | Time in seconds to wait for a response after connecting.                     | `10`                     | No       |
+| `:blacklist_duration_minutes` | The duration in minutes to temporarily blacklist a suggested IP.             | `5`                      | No       |
+
+### Verifying the Installation
+
+The Smart Proxy will test its connection to the Kea API upon initialisation. Due to lazy loading, this check runs **on the first DHCP request** after a proxy restart, not during the initial boot sequence.
+
+Check `/var/log/foreman-proxy/proxy.log` for a "Successfully connected to Kea API" message at that time to confirm everything is working. If the connection fails, the first DHCP request will fail with an error in the log, preventing further issues.
+
+## Contributing
+
+Bug reports and pull requests are welcome on this project's GitLab page.
+
+## Licence Information
+
+<details>
+<summary>Copyright and Licence (GPLv3)</summary>
+
+Copyright © 2025 Sam McCarthy
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public Licence as published by
+the Free Software Foundation, either version 3 of the Licence or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public Licence for more details.
+
+You should have received a copy of the GNU General Public Licence
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+</details>

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_main.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'dhcp_common/server'
+require 'resolv'
+
+module Proxy
+  module DHCP
+    module KeaApi
+      # The main provider class for the `dhcp_kea_api` module. This class inherits
+      # from the Foreman Smart Proxy's core `DHCP::Server` and implements the
+      # Kea-specific logic for adding and deleting DHCP reservations.
+      class Provider < ::Proxy::DHCP::Server
+        attr_reader :subnet_service, :client
+
+        # Initialises the Kea API provider.
+        #
+        # @param subnet_service [Proxy::DHCP::KeaApi::SubnetService] The service that manages the in-memory cache of DHCP data.
+        # @param client [Proxy::DHCP::KeaApi::Client] The client for communicating with the Kea API.
+        # @param free_ips [Proxy::DHCP::FreeIps] The service that tracks recently suggested IPs to prevent race conditions.
+        def initialize(subnet_service, client, free_ips)
+          @subnet_service = subnet_service
+          @client = client
+          subnet_service.load!
+          super('localhost', nil, subnet_service, free_ips)
+        end
+
+        # Creates a new DHCP reservation in Kea.
+        # This method orchestrates the process by first calling the parent class's
+        # `add_record` to perform initial validation and IP selection, then building
+        # the Kea-specific payload and sending it via the API client.
+        #
+        # @param options [Hash] A hash of options for the new record, typically including :mac, :ip, and :name.
+        # @return [Proxy::DHCP::Reservation] The created reservation object.
+        def add_record(options = {})
+          logger.debug "DHCP options received from Foreman: #{options.inspect}"
+          record = super
+
+          reservation_args = build_base_reservation_args(record)
+          add_boot_and_server_options(reservation_args, options)
+
+          option_data = build_option_data(options)
+          reservation_args['option-data'] = option_data unless option_data.empty?
+
+          @client.post_command('dhcp4', 'reservation-add', { reservation: reservation_args })
+          subnet_service.add_host(record.subnet.network, record)
+
+          logger.info "Successfully added reservation for MAC #{record.mac} and IP #{record.ip}"
+          record
+        end
+
+        # Deletes a DHCP reservation from Kea.
+        #
+        # @param record [Proxy::DHCP::Reservation] The reservation object to be deleted.
+        # @return [Proxy::DHCP::Reservation] The deleted reservation object.
+        def del_record(record)
+          logger.debug "Deleting record; #{record.inspect}"
+          return record if record.is_a? ::Proxy::DHCP::Lease
+
+          subnet_id = @subnet_service.kea_id_map[record.subnet.network]
+          raise Proxy::DHCP::Error, "Unable to find Kea subnet-id for network #{record.subnet.network}" unless subnet_id
+
+          # Construct the arguments for the 'reservation-del' command using the identifier triplet.
+          args = {
+            'subnet-id': subnet_id,
+            'identifier-type': 'hw-address',
+            'identifier' => record.mac
+          }
+
+          @client.post_command('dhcp4', 'reservation-del', args)
+          subnet_service.delete_host(record)
+
+          logger.info "Successfully deleted reservation for MAC #{record.mac} and IP #{record.ip}"
+          record
+        end
+
+        private
+
+        # Builds the initial hash of arguments required for a Kea reservation.
+        #
+        # @param record [Proxy::DHCP::Reservation] The reservation object from the parent class.
+        # @return [Hash] A hash containing the base arguments for the Kea API.
+        def build_base_reservation_args(record)
+          subnet_id = @subnet_service.kea_id_map[record.subnet.network]
+          raise Proxy::DHCP::Error, "Unable to find Kea subnet-id for network #{record.subnet.network}" unless subnet_id
+
+          {
+            'subnet-id': subnet_id,
+            'ip-address': record.ip,
+            'hw-address': record.mac,
+            hostname: record.name
+          }
+        end
+
+        # Adds next-server and boot-file-name options to the reservation arguments hash.
+        # This method modifies the `reservation_args` hash in place.
+        #
+        # @param reservation_args [Hash] The hash of arguments to be modified.
+        # @param options [Hash] The original options hash from Foreman.
+        # @return [void]
+        def add_boot_and_server_options(reservation_args, options)
+          next_server_value = options[:nextServer]
+          reservation_args[:'next-server'] = resolve_hostname(next_server_value) unless next_server_value.to_s.empty?
+
+          reservation_args[:'boot-file-name'] = options[:filename] unless options[:filename].to_s.empty?
+        end
+
+        # Resolves a hostname to an IP address. If the provided string is already
+        # an IP, it is returned directly.
+        #
+        # @param hostname [String] The hostname or IP address string to resolve.
+        # @return [String] The resolved IPv4 address.
+        # @raise [Proxy::DHCP::Error] if the hostname cannot be resolved.
+        def resolve_hostname(hostname)
+          return hostname if hostname =~ Regexp.union(Resolv::IPv4::Regex)
+
+          Resolv.getaddress(hostname)
+        rescue Resolv::ResolvError => e
+          raise Proxy::DHCP::Error, "Could not resolve next-server hostname '#{hostname}': #{e.message}"
+        end
+
+        # Builds the array of DHCP options (e.g. routers, ntp-servers) for the reservation.
+        #
+        # @param options [Hash] The original options hash from Foreman.
+        # @return [Array<Hash>] An array of option hashes for the Kea API.
+        def build_option_data(options)
+          option_data = []
+          add_dhcp_option(option_data, 'routers', options[:routers])
+          add_dhcp_option(option_data, 'ntp-servers', options[:ntp_servers])
+          add_dhcp_option(option_data, 'domain-name', options[:domain_name])
+          option_data
+        end
+
+        # A helper to add a DHCP option to the data array if the value exists.
+        # This method modifies the `option_data` array in place.
+        #
+        # @param option_data [Array<Hash>] The array of options to be modified.
+        # @param name [String] The name of the DHCP option (e.g. 'routers').
+        # @param value [String, Array] The value of the option.
+        # @return [void]
+        def add_dhcp_option(option_data, name, value)
+          return if value.to_s.empty?
+
+          option_data << { name: name, data: Array(value).join(',') }
+        end
+      end
+    end
+  end
+end

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_plugin.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'smart_proxy_dhcp_kea_api/dhcp_kea_api_version'
+require 'smart_proxy_dhcp_kea_api/plugin_configuration'
+
+module Proxy
+  module DHCP
+    module KeaApi
+      # The main plugin class for the `dhcp_kea_api` provider. This class serves
+      # as the entry point for the Foreman Smart Proxy to load and configure the
+      # plugin. It defines the plugin's name, version, dependencies on other
+      # modules, default settings, and hooks into the dependency injection framework.
+      class Plugin < ::Proxy::Provider
+        # Registers the provider with the Smart Proxy, giving it a unique name
+        # (`:dhcp_kea_api`) and sourcing the version from the VERSION constant.
+        plugin :dhcp_kea_api, ::Proxy::DHCP::KeaApi::VERSION
+
+        # Declares a dependency on the core Smart Proxy DHCP module. This ensures
+        # that the base classes we inherit from (like DHCP::Server) are available.
+        requires :dhcp, '>= 1.17'
+
+        # Defines the default settings for this provider. These values are used if
+        # they are not explicitly overridden in a user's settings file
+        # (e.g. `/etc/foreman-proxy/settings.d/dhcp_kea_api.yml`).
+        default_settings kea_api_url: 'http://127.0.0.1:8000/',
+                         blacklist_duration_minutes: 5,
+                         open_timeout: 5,
+                         read_timeout: 10
+
+        # Hooks into the Smart Proxy's dependency injection (DI) framework. These lines
+        # delegate the responsibility of loading the required classes and wiring up
+        # their dependencies to the `PluginConfiguration` class. This keeps this
+        # main plugin file clean and declarative.
+        load_classes ::Proxy::DHCP::KeaApi::PluginConfiguration
+        load_dependency_injection_wirings ::Proxy::DHCP::KeaApi::PluginConfiguration
+
+        # Tells the Smart Proxy to start these specific services from our DI container
+        # when the provider is enabled. `:subnet_service` manages the data cache,
+        # and `:unused_ips` handles IP blacklist management.
+        start_services :subnet_service, :unused_ips
+      end
+    end
+  end
+end

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_subnet_service.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'dhcp_common/dhcp_common'
+require 'dhcp_common/subnet_service'
+
+module Proxy
+  module DHCP
+    module KeaApi
+      # Manages the in-memory cache of DHCP data for the Kea provider.
+      #
+      # This class is responsible for fetching all subnet, reservation, and lease
+      # information from the Kea API. It inherits from the core `DHCP::SubnetService`
+      # to get the underlying data structures (e.g. hashes for leases and hosts)
+      # and caching logic. Its primary public method, `load!`, orchestrates the
+      # population of this cache. It also maintains a mapping of Foreman subnet
+      # networks to their internal Kea API subnet IDs.
+      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
+        # API calls that require a `subnet-id`.
+        attr_reader :kea_id_map
+
+        # Initialises the SubnetService.
+        #
+        # @param client [Proxy::DHCP::KeaApi::Client] The client for communicating with the Kea API.
+        # @param leases_by_ip [Proxy::MemoryStore] A memory store for leases, passed to the parent class.
+        # @param leases_by_mac [Proxy::MemoryStore] A memory store for leases, passed to the parent class.
+        # @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.
+
+        # rubocop:disable Metrics/ParameterLists
+        def initialize(client, leases_by_ip, leases_by_mac, reservations_by_ip, reservations_by_mac, reservations_by_name)
+          @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.
+          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.
+        #
+        # @return [true] on success.
+        # @raise [Proxy::DHCP::Error] if any part of the loading process fails.
+        # rubocop:disable Naming/PredicateMethod
+        def load!
+          subnets.clear
+          @kea_id_map.clear
+
+          load_subnets_and_reservations_from_kea
+          load_leases_from_kea
+          true
+        end
+        # rubocop:enable Naming/PredicateMethod
+
+        # 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.
+        def load_subnets_and_reservations_from_kea
+          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)
+          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
+        rescue IPAddr::InvalidAddressError => e
+          logger.error "Failed to parse subnet from Kea, invalid address found: #{e.message}"
+          raise
+        end
+
+        # Fetches all active leases from the Kea API for the subnets currently in the cache.
+        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?
+
+          response = @client.post_command('dhcp4', 'lease4-get-all', { subnets: @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)
+          end
+        rescue Proxy::DHCP::Error => e
+          logger.error "Failed to load all leases from Kea: #{e.message}"
+          raise
+        end
+
+        private
+
+        # 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)
+          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
+
+          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']
+          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)
+          end
+        end
+
+        # Extracts and formats the router data from a subnet's options.
+        #
+        # @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(',')
+        end
+
+        # Extracts the IP range from a subnet's first pool.
+        #
+        # @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('-')
+        end
+
+        # Creates a Foreman Reservation object from Kea data and adds it to the cache.
+        #
+        # @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)
+          logger.debug "Loaded reservation for #{res_data['hw-address']} on subnet #{subnet.network}"
+        end
+      end
+    end
+  end
+end

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Proxy
+  module DHCP
+    module KeaApi
+      VERSION = '1.0.0'
+    end
+  end
+end

data/lib/smart_proxy_dhcp_kea_api/kea_api_client.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Proxy
+  module DHCP
+    module KeaApi
+      # A client for interacting with the ISC Kea DHCP server API. This class
+      # encapsulates the logic for creating JSON-RPC commands, sending them via
+      # HTTP, and handling the responses from the Kea server.
+      class Client
+        include Proxy::Log
+
+        # 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 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.
+        def initialize(url:, 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)
+
+          raise ArgumentError, "Invalid Kea API URL: '#{url}' must be an HTTP or HTTPS URL" unless @uri.is_a?(URI::HTTP) || @uri.is_a?(URI::HTTPS)
+
+          raise ArgumentError, "Invalid Kea API URL: '#{url}' is missing a host" unless @uri.host
+
+          @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)"
+        end
+
+        # Constructs and sends a command to the Kea API and handles its response.
+        # This is the main public method for interacting with the Kea server.
+        #
+        # @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.
+        def post_command(service, command, arguments = {})
+          header = { 'Content-Type' => 'application/json' }
+          payload = {
+            command: command,
+            service: [service],
+            arguments: arguments
+          }
+
+          # This guard clause satisfies strict linters by ensuring the host is not nil in the local scope.
+          host = @uri.host
+          raise 'Internal error: Kea API client URI is missing a host' unless host
+
+          http = Net::HTTP.new(host, @uri.port)
+          http.use_ssl = @uri.scheme == 'https'
+          http.open_timeout = @open_timeout
+          http.read_timeout = @read_timeout
+          request = Net::HTTP::Post.new(@uri.request_uri, header)
+          request.body = payload.to_json
+
+          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}"
+          raise Proxy::DHCP::Error, "Kea API communication error: #{e.message}"
+        end
+
+        private
+
+        # A private helper to parse the JSON response from Kea and route it based on success or failure.
+        #
+        # @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.
+        def handle_response(response, command)
+          body = JSON.parse(response.body)
+          logger.debug "Received response from Kea: #{body.inspect}"
+
+          result = body.first if body.is_a?(Array)
+          raise Proxy::DHCP::Error, 'Kea API Error: Invalid or empty response from server' unless result
+
+          # 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.
+            result['arguments'] || {}
+          else
+            error_message = result['text'] || 'Unknown error from Kea API'
+            raise Proxy::DHCP::Error, "Kea API Error: #{error_message}"
+          end
+        end
+
+        # A private predicate method to determine if a Kea response is successful.
+        #
+        # @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.
+        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
+        end
+      end
+    end
+  end
+end