smart_proxy_dhcp_kea_api 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 142ceab2eeffbc270cb77ef8193a1eabdfe44f824fb60d11f71a942b726f054b
-  data.tar.gz: 85edbf8f08b9a9c81f1ce07ec97c2b9dff7038149ee8d2f79787c9be3fe38cdf
+  metadata.gz: 60b69b716ae58881effcacb442e0357e0d92a2b30b4c5be29e24439e07c9e047
+  data.tar.gz: c698f7bdb99f3965eb1f7eb02afe908559b29c2145e3c8870b87038c3552c101
 SHA512:
-  metadata.gz: 410a191c0459dc5a854bc61ddf08fcba06519d458e337fd2b5eae3bc2afa68bf09fc8c1ffb1888725dbed5b5f5d688f8bdc7d421651ac05d377af264aa5f8391
-  data.tar.gz: ef8f1adacf0b3c33405f493325d6138d69f617c3d6287bb8c6ce2acbfb31581bc9a0e2b5160c321b5b95fc69d000f365794a9fdce62cc2351350386bdebf1500
+  metadata.gz: bd83ca3c705b98af40b57b11b9d9d10386f43277a07884d537eda07f28ef433e3939aeb5d7ab90d351e0f1f429560ea642a9a8ce0b4a98eb60867cb037c6b1e5
+  data.tar.gz: e965386db272058aa1504d089cc69e3e39ada4610a2fe96ff4e2f1a2c5ee7632577430f781e0bffc16239f7243d94f5acb536ef0e6ebcefd0558541b080a018d

data/README.md

@@ -1,5 +1,5 @@
 # Foreman Smart Proxy DHCP Kea API
-
+[![Gem Version](https://badge.fury.io/rb/smart_proxy_dhcp_kea_api.svg)](https://badge.fury.io/rb/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.

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_main.rb

@@ -29,8 +29,36 @@ module Proxy
         # `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.
+        # @param options [Hash] A hash containing the details for the new reservation.
+        # @option options [String] 'mac' The hardware address of the host.
+        # @option options [String] 'ip' The IP address to reserve.
+        # @option options [String] 'hostname' The hostname for the reservation.
+        # @option options [Proxy::DHCP::Subnet] :subnet The subnet object this reservation belongs to.
+        # @option options [String, nil] 'nextServer' (optional) The IP of the TFTP boot server.
+        # @option options [String, nil] 'filename' (optional) The boot filename (e.g., 'pxelinux.0').
         # @return [Proxy::DHCP::Reservation] The created reservation object.
+        #
+        # @example Add a new DHCP reservation for a host
+        #   # Assume @provider is an instance of Proxy::DHCP::KeaApi::Provider
+        #   # and 'subnet' is a valid Proxy::DHCP::Subnet object for '192.168.1.0/24'
+        #   options = {
+        #     'mac' => 'aa:bb:cc:dd:ee:ff',
+        #     'hostname' => 'test-host.example.com',
+        #     'ip' => '192.168.1.15',
+        #     subnet: subnet,
+        #     'nextServer' => 'tftp.example.com',
+        #     'filename' => 'pxelinux.0',
+        #     'routers' => ['192.168.1.1'],
+        #     'ntp_servers' => ['192.168.1.254']
+        #   }
+        #
+        #   reservation = @provider.add_record(options)
+        #
+        #   reservation.mac      #=> "aa:bb:cc:dd:ee:ff"
+        #   reservation.ip       #=> "192.168.1.15"
+        #   reservation.name     #=> "test-host.example.com"
+        #   reservation.subnet   #=> #<Proxy::DHCP::Subnet ...>
+        #
         def add_record(options = {})
           logger.debug "DHCP options received from Foreman: #{options.inspect}"
           record = super
@@ -51,10 +79,29 @@ module Proxy
         # 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.
+        #   This object should be retrieved from the subnet service first.
+        # @return [Proxy::DHCP::Reservation] The object that was successfully deleted.
+        # @raise [Proxy::DHCP::Error] if the corresponding Kea subnet-id cannot be found or the API call fails.
+        #
+        # @example Delete a known DHCP reservation
+        #   # Assume @provider is an instance of Proxy::DHCP::KeaApi::Provider
+        #   mac_to_delete = 'aa:bb:cc:dd:ee:ff'
+        #
+        #   # First, find the reservation object
+        #   record_to_delete = @provider.get_record('mac' => mac_to_delete)
+        #
+        #   # Now, pass the entire object to del_record
+        #   if record_to_delete
+        #     result = @provider.del_record(record_to_delete)
+        #     #=> #<Proxy::DHCP::Reservation ...>
+        #   end
+        #
         def del_record(record)
           logger.debug "Deleting record; #{record.inspect}"
-          return record if record.is_a? ::Proxy::DHCP::Lease
+          unless record.is_a?(::Proxy::DHCP::Reservation)
+            logger.warn "Attempted to delete a record for MAC '#{record.mac}' but it is not a Reservation (actual type: #{record.class.name}). No action taken."
+            return record
+          end
 
           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

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_plugin.rb

@@ -10,6 +10,8 @@ module Proxy
       # 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.
+      #
+      # @see Proxy::DHCP::KeaApi::PluginConfiguration For how dependencies are loaded and wired.
       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.

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_subnet_service.rb

@@ -60,6 +60,7 @@ 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.
+        # @see Proxy::DHCP::KeaApi::Client#post_command
         def load_subnets_and_reservations_from_kea
           config = @client.post_command('dhcp4', 'config-get')
           subnets_data = config&.dig('Dhcp4', 'subnet4')
@@ -79,6 +80,7 @@ module Proxy
         end
 
         # Fetches all active leases from the Kea API for the subnets currently in the cache.
+        # @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.

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_version.rb

@@ -3,7 +3,7 @@
 module Proxy
   module DHCP
     module KeaApi
-      VERSION = '1.0.0'
+      VERSION = '1.0.1'
     end
   end
 end

data/lib/smart_proxy_dhcp_kea_api/kea_api_client.rb

@@ -19,6 +19,16 @@ module Proxy
         # @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.
+        #
+        # @example Basic Initialization
+        #   client = Proxy::DHCP::KeaApi::Client.new(url: 'https://kea.example.com:8443')
+        #
+        # @example Initialization with Custom Timeouts
+        #   client = Proxy::DHCP::KeaApi::Client.new(
+        #     url: 'http://127.0.0.1:8000',
+        #     open_timeout: 2,
+        #     read_timeout: 5
+        #   )
         def initialize(url:, open_timeout: 5, read_timeout: 10)
           raise ArgumentError, 'Kea API URL cannot be nil or empty' if url.to_s.empty?
 
@@ -42,6 +52,23 @@ module Proxy
         #
         # @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.
+        #
+        # @example Get the current DHCPv4 configuration
+        #   client = Proxy::DHCP::KeaApi::Client.new(url: 'http://localhost:8000')
+        #   config_response = client.post_command('dhcp4', 'config-get')
+        #   # => {"Dhcp4"=>{"subnet4"=>[{"id"=>1, "subnet"=>"192.168.1.0/24", ...}]}}
+        #
+        # @example Add a DHCPv4 reservation
+        #   client = Proxy::DHCP::KeaApi::Client.new(url: 'http://localhost:8000')
+        #   add_response = client.post_command('dhcp4', 'reservation-add', {
+        #     reservation: {
+        #       'subnet-id': 1,
+        #       'ip-address': '192.168.1.100',
+        #       'hw-address': '00:11:22:33:44:55',
+        #       hostname: 'my-new-host'
+        #     }
+        #   })
+        #   # => {"text"=>"Reservation added successfully."}
         def post_command(service, command, arguments = {})
           header = { 'Content-Type' => 'application/json' }
           payload = {
@@ -82,6 +109,7 @@ module Proxy
         #
         # @return [Hash] The 'arguments' hash from the response on success.
         # @raise [Proxy::DHCP::Error] if the response indicates a failure or is malformed.
+        # @private
         def handle_response(response, command)
           body = JSON.parse(response.body)
           logger.debug "Received response from Kea: #{body.inspect}"
@@ -105,6 +133,7 @@ module Proxy
         # @param command [String] The original command sent, needed for special case handling.
         #
         # @return [Boolean] `true` if the response is considered a success, `false` otherwise.
+        # @private
         def response_successful?(result, command)
           # Universal success is result code 0.
           return true if result['result'].zero?

data/lib/smart_proxy_dhcp_kea_api/plugin_configuration.rb

@@ -38,6 +38,7 @@ module Proxy
 
           # 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.
+          # @see Proxy::DHCP::KeaApi::Client#initialize
           container.singleton_dependency :kea_client, (lambda do
             ::Proxy::DHCP::KeaApi::Client.new(
               url: settings[:kea_api_url],
@@ -50,6 +51,7 @@ module Proxy
           # 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.
+          # @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(
@@ -65,6 +67,7 @@ module Proxy
           # The main provider class that ties everything together. This is the entry point
           # 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
             ::Proxy::DHCP::KeaApi::Provider.new(
               container.get_dependency(:subnet_service),

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smart_proxy_dhcp_kea_api
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Sam McCarthy