durable-proxmox-ruby 0.1.0

data/lib/durable_proxmox/dsl.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+module DurableProxmox
+  # DSL for declaratively defining Proxmox VMs.
+  #
+  # Example:
+  #   DurableProxmox::DSL.configure do
+  #     vm 'web-server-1' do
+  #       ip '192.168.2.100'
+  #       template_id 911
+  #     end
+  #   end
+  class DSL
+    # @return [Array<VMDefinition>] List of defined VMs
+    attr_reader :vms
+
+    # @return [DurableProxmox::Client] The Proxmox client
+    attr_reader :client
+
+    # Executes a DSL configuration block.
+    #
+    # @param client [DurableProxmox::Client, nil] The Proxmox client (creates one if nil)
+    # @param insecure [Boolean] Skip SSL certificate validation (default: false)
+    # @yield Block with VM definitions
+    # @return [DSL] The DSL instance
+    def self.configure(client = nil, insecure: false, &block)
+      dsl = new(client, insecure: insecure)
+      dsl.instance_eval(&block)
+      dsl
+    end
+
+    # Creates a new DSL instance.
+    #
+    # @param client [DurableProxmox::Client, nil] The Proxmox client
+    # @param insecure [Boolean] Skip SSL certificate validation (default: false)
+    def initialize(client = nil, insecure: false)
+      @client = client || Client.new(nil, insecure: insecure)
+      @vms = []
+    end
+
+    # Defines a VM in the DSL.
+    #
+    # @param name [String] The VM hostname
+    # @yield Block with VM configuration
+    # @return [VMDefinition] The VM definition
+    def vm(name, &block)
+      vm_def = VMDefinition.new(name, @client)
+      vm_def.instance_eval(&block) if block_given?
+      @vms << vm_def
+      vm_def
+    end
+
+    # Applies all VM definitions (create or update VMs).
+    #
+    # @param node [DurableProxmox::Node, nil] The target node (uses first node if nil)
+    # @return [Array<Hash>] Results for each VM
+    def apply(node = nil)
+      target_node = node || @client.nodes.first
+      @vms.map { |vm_def| vm_def.apply(target_node) }
+    end
+
+    # Plans all VM definitions (shows what would be done without executing).
+    #
+    # @param node [DurableProxmox::Node, nil] The target node (uses first node if nil)
+    # @return [Array<Hash>] Plan for each VM
+    def plan(node = nil)
+      target_node = node || @client.nodes.first
+      @vms.map { |vm_def| vm_def.plan(target_node) }
+    end
+  end
+
+  # Represents a VM definition in the DSL.
+  class VMDefinition
+    # @return [String] VM hostname
+    attr_reader :name
+
+    # @return [String, nil] IP address
+    attr_reader :ip
+
+    # @return [String, nil] Gateway address
+    attr_reader :gateway
+
+    # @return [Integer, nil] Template VM ID for cloning
+    attr_reader :template_id
+
+    # @return [Integer, nil] Number of CPU cores
+    attr_reader :cores
+
+    # @return [Integer, nil] Memory in MB
+    attr_reader :memory
+
+    # @return [Integer, nil] Specific VMID to use
+    attr_reader :vmid
+
+    # @return [Array<String>, nil] DNS server addresses
+    attr_reader :dns_servers
+
+    # @return [DurableProxmox::Client] The Proxmox client
+    attr_reader :client
+
+    # Creates a new VM definition.
+    #
+    # @param name [String] The VM hostname
+    # @param client [DurableProxmox::Client] The Proxmox client
+    def initialize(name, client)
+      @name = name
+      @client = client
+      @template_id = (ENV["SOURCE_VMID"] || 911).to_i
+    end
+
+    # Sets the IP address for the VM.
+    #
+    # @param value [String, nil] The IP address (returns current value if nil)
+    # @return [String, nil] The IP address
+    def ip(value = nil)
+      return @ip if value.nil?
+      @ip = value
+    end
+
+    # Sets the gateway address for the VM.
+    #
+    # @param value [String, nil] The gateway address (returns current value if nil)
+    # @return [String, nil] The gateway address
+    def gateway(value = nil)
+      return @gateway if value.nil?
+      @gateway = value
+    end
+
+    # Sets the template ID for cloning.
+    #
+    # @param value [Integer, nil] The template VM ID (returns current value if nil)
+    # @return [Integer, nil] The template ID
+    def template_id(value = nil)
+      return @template_id if value.nil?
+      @template_id = value
+    end
+
+    # Sets the number of CPU cores.
+    #
+    # @param value [Integer, nil] Number of cores (returns current value if nil)
+    # @return [Integer, nil] The number of cores
+    def cores(value = nil)
+      return @cores if value.nil?
+      @cores = value
+    end
+
+    # Sets the memory size.
+    #
+    # @param value [Integer, nil] Memory in MB (returns current value if nil)
+    # @return [Integer, nil] The memory size
+    def memory(value = nil)
+      return @memory if value.nil?
+      @memory = value
+    end
+
+    # Sets a specific VMID.
+    #
+    # @param value [Integer, nil] The VMID (returns current value if nil)
+    # @return [Integer, nil] The VMID
+    def vmid(value = nil)
+      return @vmid if value.nil?
+      @vmid = value
+    end
+
+    # Sets DNS server addresses.
+    #
+    # @param servers [Array<String>, String] DNS server IP address(es) (returns current value if empty)
+    # @return [Array<String>, nil] The DNS servers
+    def dns_servers(*servers)
+      return @dns_servers if servers.empty?
+      @dns_servers = servers.flatten
+    end
+
+    # Applies this VM definition (creates or updates the VM).
+    #
+    # @param node [DurableProxmox::Node] The target node
+    # @return [Hash] Result with VM details
+    def apply(node)
+      # Check if VM already exists
+      existing_vm = node.vms.find { |vm| vm.name == @name }
+
+      if existing_vm
+        update_vm(existing_vm, node)
+      else
+        create_vm(node)
+      end
+    end
+
+    # Plans this VM definition (shows what would be done without executing).
+    #
+    # @param node [DurableProxmox::Node] The target node
+    # @return [Hash] Plan with VM details
+    def plan(node)
+      # Check if VM already exists
+      existing_vm = node.vms.find { |vm| vm.name == @name }
+
+      if existing_vm
+        plan_update(existing_vm, node)
+      else
+        plan_create(node)
+      end
+    end
+
+    private
+
+    # Creates a new VM from this definition.
+    #
+    # @param node [DurableProxmox::Node] The target node
+    # @return [Hash] Result with VM details
+    def create_vm(node)
+      # Clone from template
+      new_vmid = @vmid || node.get_next_vmid
+      puts "Creating VM '#{@name}' (vmid: #{new_vmid}) from template #{@template_id}..."
+
+      params = {
+        newid: new_vmid,
+        target: node.node_id,
+        name: @name,
+        full: 1
+      }
+
+      response = @client.post("nodes/#{node.node_id}/qemu/#{@template_id}/clone", params)
+      resp = response.body.dig("data")
+
+      if resp
+        print "Cloning VM"
+        @client.wait_for_upid(node.node_id, resp)
+      end
+
+      # Update configuration
+      node.clear_cache
+      vm = node.vms.find { |v| v.vm_id == new_vmid }
+
+      if vm
+        puts "VM '#{@name}' created successfully (vmid: #{new_vmid})"
+        apply_configuration(vm, node)
+      end
+
+      {
+        action: "created",
+        name: @name,
+        vmid: new_vmid,
+        ip: @ip
+      }
+    end
+
+    # Updates an existing VM with this definition.
+    #
+    # @param vm [DurableProxmox::VM] The existing VM
+    # @param node [DurableProxmox::Node] The node
+    # @return [Hash] Result with VM details
+    def update_vm(vm, node)
+      puts "Updating VM '#{@name}' (vmid: #{vm.vm_id})..."
+      apply_configuration(vm, node)
+      puts "VM '#{@name}' updated successfully"
+
+      {
+        action: "updated",
+        name: @name,
+        vmid: vm.vm_id,
+        ip: @ip
+      }
+    end
+
+    # Applies configuration to a VM.
+    #
+    # @param vm [DurableProxmox::VM] The VM to configure
+    # @param node [DurableProxmox::Node] The node
+    def apply_configuration(vm, node)
+      config_params = {}
+
+      config_params[:cores] = @cores if @cores
+      config_params[:memory] = @memory if @memory
+
+      # Set IP via cloud-init ipconfig
+      if @ip
+        # Format: ip=192.168.1.100/24,gw=192.168.1.1
+        # If IP already has a netmask, use it as-is; otherwise default to /24
+        ip_with_netmask = @ip.include?('/') ? @ip : "#{@ip}/24"
+        ipconfig = "ip=#{ip_with_netmask}"
+
+        # Use specified gateway, or preserve existing gateway if not specified
+        gateway_to_use = @gateway
+        if gateway_to_use.nil? && vm.config["ipconfig0"]
+          # Extract existing gateway from ipconfig0 (format: ip=x.x.x.x/24,gw=y.y.y.y)
+          existing_ipconfig = vm.config["ipconfig0"]
+          if existing_ipconfig =~ /gw=([^,]+)/
+            gateway_to_use = ::Regexp.last_match(1)
+          end
+        end
+
+        ipconfig += ",gw=#{gateway_to_use}" if gateway_to_use
+        config_params[:ipconfig0] = ipconfig
+      end
+
+      # Set DNS servers via cloud-init nameserver
+      if @dns_servers && !@dns_servers.empty?
+        config_params[:nameserver] = @dns_servers.join(" ")
+      end
+
+      unless config_params.empty?
+        puts "  Applying configuration: #{config_params.inspect}"
+        @client.post("nodes/#{node.node_id}/qemu/#{vm.vm_id}/config", config_params)
+        puts "  Configuration applied successfully"
+      end
+    end
+
+    # Plans VM creation without executing.
+    #
+    # @param node [DurableProxmox::Node] The target node
+    # @return [Hash] Plan with VM details
+    def plan_create(node)
+      planned_vmid = @vmid || node.get_next_vmid
+      planned_config = build_config_params
+
+      {
+        action: "create",
+        name: @name,
+        vmid: planned_vmid,
+        template_id: @template_id,
+        configuration: planned_config
+      }
+    end
+
+    # Plans VM update without executing.
+    #
+    # @param vm [DurableProxmox::VM] The existing VM
+    # @param node [DurableProxmox::Node] The node
+    # @return [Hash] Plan with VM details
+    def plan_update(vm, node)
+      current_config = vm.config
+      planned_config = build_config_params
+
+      # Only include changes
+      changes = {}
+      planned_config.each do |key, value|
+        current_value = if key == :ipconfig0
+                         current_config["ipconfig0"]
+                       else
+                         current_config[key.to_s]
+                       end
+
+        changes[key] = { from: current_value, to: value } if current_value != value
+      end
+
+      {
+        action: "update",
+        name: @name,
+        vmid: vm.vm_id,
+        changes: changes
+      }
+    end
+
+    # Builds configuration parameters from the definition.
+    #
+    # @return [Hash] Configuration parameters
+    def build_config_params
+      config_params = {}
+
+      config_params[:cores] = @cores if @cores
+      config_params[:memory] = @memory if @memory
+      if @ip
+        # If IP already has a netmask, use it as-is; otherwise default to /24
+        ip_with_netmask = @ip.include?('/') ? @ip : "#{@ip}/24"
+        ipconfig = "ip=#{ip_with_netmask}"
+        ipconfig += ",gw=#{@gateway}" if @gateway
+        config_params[:ipconfig0] = ipconfig
+      end
+      config_params[:nameserver] = @dns_servers.join(" ") if @dns_servers && !@dns_servers.empty?
+
+      config_params
+    end
+  end
+end

data/lib/durable_proxmox/errors.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module DurableProxmox
+  # Base error class for all DurableProxmox errors.
+  class Error < StandardError; end
+
+  # Raised when authentication fails or credentials are invalid.
+  class AuthenticationError < Error; end
+
+  # Raised when a requested resource (VM, node, etc.) is not found.
+  class NotFoundError < Error; end
+
+  # Raised when input validation fails.
+  class ValidationError < Error; end
+
+  # Raised when the Proxmox API returns an error response.
+  class APIError < Error
+    # @return [Integer, nil] HTTP status code
+    attr_reader :status_code
+
+    # @return [Hash, nil] Response body from the API
+    attr_reader :response_body
+
+    # Creates a new APIError.
+    #
+    # @param message [String] Error message
+    # @param status_code [Integer, nil] HTTP status code
+    # @param response_body [Hash, nil] Response body from the API
+    def initialize(message, status_code: nil, response_body: nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
+
+  # Raised when a request times out.
+  class TimeoutError < Error; end
+
+  # Raised when the QEMU guest agent is not available or not responding.
+  class GuestAgentError < Error; end
+
+  # Raised when a network connection fails.
+  class ConnectionError < Error; end
+end

data/lib/durable_proxmox/ip_address_group.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module DurableProxmox
+  # Utility class for managing groups of IP addresses.
+  #
+  # Provides methods for filtering, finding ranges, and identifying missing IPs.
+  class IPAddressGroup
+    # @return [Array] The group of IP addresses or interface data
+    attr_accessor :group
+
+    # Creates a new IP address group.
+    #
+    # @param group [Array] Array of IP addresses or interface data
+    def initialize(group)
+      @group = group
+    end
+
+    # Returns the number of items in the group.
+    #
+    # @return [Integer] The length of the group
+    def length
+      @group.length
+    end
+
+    # Converts the group to an array.
+    #
+    # @return [Array] The group as an array
+    def to_a
+      @group
+    end
+
+    # Filters the group to include only IPv4 addresses (for interfaces).
+    #
+    # @return [DurableProxmox::IPAddressGroup] New group with only IPv4 addresses
+    def ipv4
+      IPAddressGroup.new(
+        @group.select { |ip| ip["ip-address-type"] == "ipv4" }
+      )
+    end
+
+    # Returns the minimum IP address in the group.
+    #
+    # @return [IPAddr] The minimum IP address
+    def min
+      ip_addresses.min
+    end
+
+    # Returns the maximum IP address in the group.
+    #
+    # @return [IPAddr] The maximum IP address
+    def max
+      ip_addresses.max
+    end
+
+    # Returns the IP address range from min to max.
+    #
+    # @return [Range] The IP address range
+    def range
+      min..max
+    end
+
+    # Finds IP addresses that are missing from the range.
+    #
+    # @return [Array<IPAddr>] Array of missing IP addresses
+    def missing
+      range.to_a - ip_addresses
+    end
+
+    # Converts the group to IPAddr objects.
+    #
+    # @return [Array<IPAddr>] Array of IPAddr objects
+    def ip_addresses
+      octets.map { |octet| IPAddr.new(octet) }
+    end
+
+    # Filters the group to include only addresses within specified subnets.
+    #
+    # @param subnets [Array<String>] Array of subnet specifications
+    # @return [DurableProxmox::IPAddressGroup] New group filtered by subnets
+    def in_subnets(*subnets)
+      subnets = subnets.map { |subnet| IPAddr.new(subnet) }
+      IPAddressGroup.new(
+        @group.select do |interface|
+          ip = IPAddr.new(interface["ip-address"] || interface["ipaddr"])
+          subnets.any? { |subnet| subnet.include?(ip) }
+        end
+      )
+    end
+
+    # Extracts IP address octets from the group data.
+    #
+    # @return [Array<String>] Array of IP address strings
+    def octets
+      @group.map { |item| item["ip-address"] || item["ipaddr"] || item }
+    end
+  end
+end

data/lib/durable_proxmox/node.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module DurableProxmox
+  # Represents a Proxmox node (physical server).
+  #
+  # Provides access to VMs, LXC containers, and node operations.
+  class Node
+    # @return [String] Node name
+    attr_reader :name
+
+    # @return [String] Node status
+    attr_reader :status
+
+    # @return [Float] CPU usage
+    attr_reader :cpu
+
+    # @return [Float] Memory usage
+    attr_reader :memory
+
+    # @return [DurableProxmox::Client] The client instance
+    attr_reader :client
+
+    # @return [String] Node identifier
+    attr_reader :node_id
+
+    # Creates a new node instance.
+    #
+    # @param data [Hash] Node data from the API
+    # @param client [DurableProxmox::Client] The client instance
+    def initialize(data, client)
+      @client = client
+      @name = data["name"]
+      @node_id = data["node"]
+      @status = data["status"]
+      @cpu = data["cpu"]
+      @memory = data["memory"]
+      @cache = {}
+    end
+
+    # Clears the internal cache.
+    #
+    # Useful when the node state has changed externally.
+    def clear_cache
+      @cache.clear
+    end
+
+    # Deletes a VM from this node.
+    #
+    # @param vm [DurableProxmox::VM] The VM to delete
+    # @return [Hash] The response body
+    def delete_vm(vm)
+      puts "Deleting VM #{vm.vm_id} (#{vm.name}) from node #{node_id}..."
+      resp = @client.delete("nodes/#{node_id}/qemu/#{vm.vm_id}")
+      upid = resp.body.dig("data")
+
+      if upid
+        @client.wait_for_upid(node_id, upid)
+        puts "VM #{vm.vm_id} (#{vm.name}) deleted successfully"
+      end
+
+      resp.body
+    end
+
+    # Clones a VM from the source template and assigns it a hostname.
+    #
+    # @param hostname [String] The hostname for the new VM
+    # @return [Integer] The new VM ID
+    def spawn_vm(hostname)
+      source_vmid = (ENV["SOURCE_VMID"] || 911).to_i
+      new_vmid = get_next_vmid
+
+      puts "Spawning VM '#{hostname}' (vmid: #{new_vmid}) from template #{source_vmid}..."
+
+      params = { newid: new_vmid, target: @node_id, name: hostname, full: 1 }
+
+      resp = @client.post("nodes/#{node_id}/qemu/#{source_vmid}/clone", params).body.dig("data")
+
+      sleep 1
+
+      if resp
+        print "Cloning VM"
+        @client.wait_for_upid(node_id, resp)
+      end
+
+      data = @client.get("nodes/#{node_id}/qemu/#{new_vmid}/config").body["data"] || {}
+
+      puts "VM '#{hostname}' spawned successfully (vmid: #{new_vmid})"
+
+      new_vmid
+    end
+
+    # Finds the next available VM ID.
+    #
+    # @return [Integer] The next available VM ID
+    def get_next_vmid
+      vmids = vms.map { |vm| vm.vm_id.to_i }.sort
+      lxcids = lxcs.map { |lxc| lxc["vmid"].to_i }.sort
+      excluded_vmids = [148]
+
+      upper = vmids.max || 100
+      lower = vmids.min || 0
+
+      missing = (lower..upper).to_a - vmids - lxcids - excluded_vmids
+      missing.first || upper + 1 || 101
+    end
+
+    # Retrieves LXC containers on this node.
+    #
+    # @return [Array<Hash>] Array of LXC container data
+    def lxcs
+      @cache[:lxcs] ||= @client.get("nodes/#{node_id}/lxc").body["data"]
+    end
+
+    # Retrieves VMs on this node.
+    #
+    # @return [Array<DurableProxmox::VM>] Array of VM objects
+    def vms
+      @cache[:vms] ||= @client.get("nodes/#{node_id}/qemu").body["data"].map do |data|
+        VM.new(data, self, @client)
+      end
+    end
+  end
+end

data/lib/durable_proxmox/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DurableProxmox
+  VERSION = "0.1.0"
+end