pvectl 0.2.0

data/lib/pvectl/selectors/vm.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Selectors
+    # Selector for filtering VMs.
+    #
+    # Extends Base with VM-specific field extraction.
+    # Supports: status, tags, pool, name, template.
+    #
+    # @example Filter running VMs
+    #   selector = Vm.parse("status=running")
+    #   running_vms = selector.apply(all_vms)
+    #
+    # @example Filter by multiple criteria
+    #   selector = Vm.parse("status=running,tags=prod")
+    #   filtered = selector.apply(all_vms)
+    #
+    # @example Filter by name pattern
+    #   selector = Vm.parse("name=~web-*")
+    #   web_vms = selector.apply(all_vms)
+    #
+    class Vm < Base
+      SUPPORTED_FIELDS = %w[status tags pool name template].freeze
+
+      # Applies selector to VM collection.
+      #
+      # @param vms [Array<Models::Vm>] VMs to filter
+      # @return [Array<Models::Vm>] Filtered VMs
+      def apply(vms)
+        return vms if empty?
+
+        vms.select { |vm| matches?(vm) }
+      end
+
+      protected
+
+      # Extracts field value from VM model.
+      #
+      # @param vm [Models::Vm] VM model
+      # @param field [String] Field name (status, tags, pool, name, template)
+      # @return [String, nil] Field value
+      # @raise [ArgumentError] if field is not supported
+      def extract_value(vm, field)
+        case field
+        when "status"
+          vm.status
+        when "tags"
+          vm.tags
+        when "pool"
+          vm.pool
+        when "name"
+          vm.name
+        when "template"
+          vm.template? ? "yes" : "no"
+        else
+          raise ArgumentError, "Unknown field: #{field}. Supported: #{SUPPORTED_FIELDS.join(', ')}"
+        end
+      end
+
+      # Override to handle tags specially.
+      # Tags in Proxmox are semicolon-separated: "tag1;tag2;tag3"
+      # Selector "tags=prod" should match if "prod" is one of the tags.
+      #
+      # @param vm [Models::Vm] VM model
+      # @param condition [Hash] Condition
+      # @return [Boolean] true if matches
+      def match_condition?(vm, condition)
+        return match_tags_condition?(vm, condition) if condition[:field] == "tags"
+        return super(vm, normalize_boolean_condition(condition)) if condition[:field] == "template"
+
+        super
+      end
+
+      private
+
+      # Normalizes boolean condition values for template field.
+      # Accepts: yes/no, true/false, 1/0
+      #
+      # @param condition [Hash] Condition with :value key
+      # @return [Hash] Condition with normalized value
+      def normalize_boolean_condition(condition)
+        normalized = case condition[:value]
+                     when "true", "1" then "yes"
+                     when "false", "0" then "no"
+                     else condition[:value]
+                     end
+        condition.merge(value: normalized)
+      end
+
+      # Special matching for tags field.
+      # Proxmox tags are semicolon-separated, so we check if the value
+      # is contained in the tag list.
+      #
+      # @param vm [Models::Vm] VM model
+      # @param condition [Hash] Condition
+      # @return [Boolean] true if matches
+      def match_tags_condition?(vm, condition)
+        tags_string = vm.tags || ""
+        tag_list = tags_string.split(";").map(&:strip)
+
+        case condition[:operator]
+        when :eq
+          tag_list.include?(condition[:value])
+        when :neq
+          !tag_list.include?(condition[:value])
+        when :match
+          tag_list.any? { |tag| wildcard_match?(tag, condition[:value]) }
+        when :in
+          (tag_list & condition[:value]).any?
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/selectors/volume.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Selectors
+    # Selector for filtering virtual disk volumes.
+    #
+    # Extends Base with volume-specific field extraction.
+    # Supports: format, storage, node, content, resource_type, name.
+    #
+    # @example Filter raw volumes only
+    #   selector = Volume.parse("format=raw")
+    #   raw_vols = selector.apply(all_volumes)
+    #
+    # @example Filter volumes on a specific storage and node
+    #   selector = Volume.parse("storage=local-lvm,node=pve1")
+    #   filtered = selector.apply(all_volumes)
+    #
+    class Volume < Base
+      SUPPORTED_FIELDS = %w[format storage node content resource_type name].freeze
+
+      # Applies selector to volume collection.
+      #
+      # @param volumes [Array<Models::Volume>] volumes to filter
+      # @return [Array<Models::Volume>] filtered volumes
+      def apply(volumes)
+        return volumes if empty?
+
+        volumes.select { |vol| matches?(vol) }
+      end
+
+      protected
+
+      # Extracts field value from Volume model.
+      #
+      # @param vol [Models::Volume] volume model
+      # @param field [String] field name
+      # @return [String, nil] field value
+      # @raise [ArgumentError] if field is not supported
+      def extract_value(vol, field)
+        case field
+        when "format"
+          vol.format
+        when "storage"
+          vol.storage
+        when "node"
+          vol.node
+        when "content"
+          vol.content
+        when "resource_type"
+          vol.resource_type
+        when "name"
+          vol.name
+        else
+          raise ArgumentError, "Unknown field: #{field}. Supported: #{SUPPORTED_FIELDS.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/services/backup.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates backup operations.
+    #
+    # Handles creating, listing, deleting, and restoring backups
+    # for VMs and containers with multi-ID support and error handling.
+    #
+    # @example Basic usage
+    #   service = Backup.new(
+    #     backup_repo: backup_repo,
+    #     resource_resolver: resolver,
+    #     task_repo: task_repo
+    #   )
+    #   backups = service.list(vmid: 100)
+    #
+    class Backup
+      DEFAULT_TIMEOUT = 300 # 5 minutes for backups
+
+      # Creates a new Backup service.
+      #
+      # @param backup_repo [Repositories::Backup] Backup repository
+      # @param resource_resolver [Utils::ResourceResolver] Resource resolver
+      # @param task_repo [Repositories::Task] Task repository
+      # @param options [Hash] Options (timeout, async, fail_fast)
+      def initialize(backup_repo:, resource_resolver:, task_repo:, options: {})
+        @backup_repo = backup_repo
+        @resolver = resource_resolver
+        @task_repo = task_repo
+        @options = options
+      end
+
+      # Lists backups with optional filtering.
+      #
+      # @param vmid [Integer, nil] filter by VM ID
+      # @param storage [String, nil] filter by storage
+      # @return [Array<Models::Backup>]
+      def list(vmid: nil, storage: nil)
+        @backup_repo.list(vmid: vmid, storage: storage)
+      end
+
+      # Creates backups for multiple VMs.
+      #
+      # @param vmids [Array<Integer>] VM IDs
+      # @param storage [String] target storage
+      # @param mode [String] backup mode (snapshot/suspend/stop)
+      # @param compress [String] compression (zstd/gzip/lzo/0)
+      # @param notes [String, nil] backup notes
+      # @param protected [Boolean] protect backup
+      # @return [Array<Models::OperationResult>]
+      def create(vmids, storage:, mode: "snapshot", compress: "zstd", notes: nil, protected: false)
+        resources = @resolver.resolve_multiple(vmids)
+        return [] if resources.empty?
+
+        execute_multi(resources, :create) do |resource|
+          @backup_repo.create(
+            resource[:vmid],
+            resource[:node],
+            storage: storage,
+            mode: mode,
+            compress: compress,
+            notes: notes,
+            protected: protected
+          )
+        end
+      end
+
+      # Deletes a backup.
+      #
+      # @param volid [String] backup volume ID
+      # @return [Models::OperationResult]
+      def delete(volid)
+        node = find_node_for_volid(volid)
+
+        upid = @backup_repo.delete(volid, node)
+
+        if @options[:async]
+          Models::OperationResult.new(
+            resource: { volid: volid, node: node },
+            operation: :delete,
+            task_upid: upid,
+            success: :pending
+          )
+        else
+          task = @task_repo.wait(upid, timeout: timeout)
+          Models::OperationResult.new(
+            resource: { volid: volid, node: node },
+            operation: :delete,
+            task: task,
+            success: task.successful?
+          )
+        end
+      rescue StandardError => e
+        Models::OperationResult.new(
+          resource: { volid: volid },
+          operation: :delete,
+          success: false,
+          error: e.message
+        )
+      end
+
+      # Restores a backup to a VM/container.
+      #
+      # @param volid [String] backup volume ID
+      # @param vmid [Integer] target VM ID
+      # @param storage [String, nil] target storage
+      # @param force [Boolean] overwrite existing
+      # @param start [Boolean] start after restore
+      # @param unique [Boolean] regenerate unique properties
+      # @return [Models::OperationResult]
+      def restore(volid, vmid:, storage: nil, force: false, start: false, unique: false)
+        node = find_node_for_volid(volid)
+
+        upid = @backup_repo.restore(
+          volid,
+          node,
+          vmid: vmid,
+          storage: storage,
+          force: force,
+          start: start,
+          unique: unique
+        )
+
+        if @options[:async]
+          Models::OperationResult.new(
+            resource: { volid: volid, vmid: vmid, node: node },
+            operation: :restore,
+            task_upid: upid,
+            success: :pending
+          )
+        else
+          task = @task_repo.wait(upid, timeout: timeout)
+          Models::OperationResult.new(
+            resource: { volid: volid, vmid: vmid, node: node },
+            operation: :restore,
+            task: task,
+            success: task.successful?
+          )
+        end
+      rescue StandardError => e
+        Models::OperationResult.new(
+          resource: { volid: volid, vmid: vmid },
+          operation: :restore,
+          success: false,
+          error: e.message
+        )
+      end
+
+      private
+
+      def execute_multi(resources, operation)
+        results = []
+
+        resources.each do |resource|
+          result = execute_single(resource, operation) { yield(resource) }
+          results << result
+
+          break if @options[:fail_fast] && result.failed?
+        end
+
+        results
+      end
+
+      def execute_single(resource, operation)
+        upid = yield
+
+        if @options[:async]
+          Models::OperationResult.new(
+            resource: resource,
+            operation: operation,
+            task_upid: upid,
+            success: :pending
+          )
+        else
+          task = @task_repo.wait(upid, timeout: timeout)
+          Models::OperationResult.new(
+            resource: resource,
+            operation: operation,
+            task: task,
+            success: task.successful?
+          )
+        end
+      rescue StandardError => e
+        Models::OperationResult.new(
+          resource: resource,
+          operation: operation,
+          success: false,
+          error: e.message
+        )
+      end
+
+      def timeout
+        @options[:timeout] || DEFAULT_TIMEOUT
+      end
+
+      # Finds the node for a backup by searching all backups.
+      #
+      # @param volid [String] backup volume ID
+      # @return [String] node name
+      # @raise [StandardError] if backup not found
+      def find_node_for_volid(volid)
+        backups = @backup_repo.list
+        backup = backups.find { |b| b.volid == volid }
+        backup&.node || raise("Backup not found: #{volid}")
+      end
+    end
+  end
+end

data/lib/pvectl/services/clone_container.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates container clone operations.
+    #
+    # Handles validation, auto-generation of CTID/hostname, and sync/async modes.
+    # Supports both full clones and linked clones (templates only).
+    #
+    # @example Full clone with auto-generated CTID
+    #   service = CloneContainer.new(container_repository: ct_repo, task_repository: task_repo)
+    #   result = service.execute(ctid: 100)
+    #
+    # @example Linked clone to specific node
+    #   service = CloneContainer.new(container_repository: ct_repo, task_repository: task_repo)
+    #   result = service.execute(ctid: 100, linked: true, target_node: "pve2")
+    #
+    # @example Async clone with custom timeout
+    #   service = CloneContainer.new(container_repository: ct_repo, task_repository: task_repo, options: { async: true })
+    #   result = service.execute(ctid: 100, new_ctid: 200, hostname: "web-clone")
+    #
+    class CloneContainer
+      DEFAULT_TIMEOUT = 300
+
+      # @return [Integer] Default timeout for start operations (seconds)
+      START_TIMEOUT = 60
+
+      # Creates a new CloneContainer service.
+      #
+      # @param container_repository [Repositories::Container] Container repository
+      # @param task_repository [Repositories::Task] Task repository
+      # @param options [Hash] Options (timeout, async)
+      def initialize(container_repository:, task_repository:, options: {})
+        @container_repository = container_repository
+        @task_repository = task_repository
+        @options = options
+      end
+
+      # Executes clone operation.
+      #
+      # Performs a two-step flow: clone the container first, then optionally apply
+      # config updates via PUT /nodes/{node}/lxc/{ctid}/config.
+      #
+      # @param ctid [Integer] Source container identifier
+      # @param node [String, nil] Source node (auto-detected from container if nil)
+      # @param new_ctid [Integer, nil] New CTID (auto-selected if nil)
+      # @param hostname [String, nil] Hostname for clone (auto-generated if nil)
+      # @param target_node [String, nil] Target node for clone
+      # @param storage [String, nil] Target storage
+      # @param linked [Boolean] Linked clone (default: false, requires template)
+      # @param pool [String, nil] Resource pool
+      # @param description [String, nil] Description
+      # @param config_params [Hash] Container config parameters to apply after clone
+      # @return [Models::ContainerOperationResult] Clone result
+      def execute(ctid:, node: nil, new_ctid: nil, hostname: nil, target_node: nil,
+                  storage: nil, linked: false, pool: nil, description: nil,
+                  config_params: {})
+        source_ct = @container_repository.get(ctid)
+        return container_not_found_error(ctid) unless source_ct
+
+        if linked && !source_ct.template?
+          return linked_clone_error(source_ct)
+        end
+
+        node ||= source_ct.node
+        new_ctid ||= @container_repository.next_available_ctid
+        hostname ||= generate_hostname(source_ct)
+
+        clone_options = build_clone_options(
+          hostname: hostname, target_node: target_node, storage: storage,
+          linked: linked, pool: pool, description: description
+        )
+
+        upid = @container_repository.clone(ctid, node, new_ctid, clone_options)
+        resource_info = { new_ctid: new_ctid, hostname: hostname, node: target_node || node }
+
+        if @options[:async]
+          Models::ContainerOperationResult.new(
+            container: source_ct, operation: :clone,
+            task_upid: upid, success: :pending,
+            resource: resource_info
+          )
+        else
+          task = @task_repository.wait(upid, timeout: timeout)
+
+          unless task.successful?
+            return Models::ContainerOperationResult.new(
+              container: source_ct, operation: :clone,
+              task: task, success: task.successful?,
+              resource: resource_info
+            )
+          end
+
+          if config_params.any?
+            apply_config_update(source_ct, new_ctid, resource_info[:node], config_params, resource_info)
+          else
+            start_container(new_ctid, resource_info[:node]) if @options[:start]
+            Models::ContainerOperationResult.new(
+              container: source_ct, operation: :clone,
+              task: task, success: true,
+              resource: resource_info
+            )
+          end
+        end
+      rescue StandardError => e
+        Models::ContainerOperationResult.new(
+          container: source_ct, operation: :clone,
+          success: false, error: e.message
+        )
+      end
+
+      private
+
+      # Generates clone hostname from source container.
+      #
+      # @param source_ct [Models::Container] Source container
+      # @return [String] Generated hostname
+      def generate_hostname(source_ct)
+        if source_ct.name && !source_ct.name.empty?
+          "#{source_ct.name}-clone"
+        else
+          "ct-#{source_ct.vmid}-clone"
+        end
+      end
+
+      # Builds clone options hash for repository call.
+      #
+      # @param hostname [String] Clone hostname
+      # @param target_node [String, nil] Target node
+      # @param storage [String, nil] Target storage
+      # @param linked [Boolean] Linked clone flag
+      # @param pool [String, nil] Resource pool
+      # @param description [String, nil] Description
+      # @return [Hash] Clone options
+      def build_clone_options(hostname:, target_node:, storage:, linked:, pool:, description:)
+        opts = { hostname: hostname, full: !linked }
+        opts[:target] = target_node if target_node
+        opts[:storage] = storage if storage
+        opts[:pool] = pool if pool
+        opts[:description] = description if description
+        opts
+      end
+
+      # Applies config update to the cloned container.
+      #
+      # Converts user-friendly params to Proxmox API format and calls
+      # the repository update method. Returns partial result on failure.
+      #
+      # @param source_ct [Models::Container] Source container
+      # @param new_ctid [Integer] Cloned container identifier
+      # @param node [String] Target node for the cloned container
+      # @param config_params [Hash] Config parameters to apply
+      # @param resource_info [Hash] Resource info for result
+      # @return [Models::ContainerOperationResult] Operation result
+      def apply_config_update(source_ct, new_ctid, node, config_params, resource_info)
+        api_params = build_ct_config_api_params(config_params)
+        @container_repository.update(new_ctid, node, api_params)
+        start_container(new_ctid, node) if @options[:start]
+        Models::ContainerOperationResult.new(
+          container: source_ct, operation: :clone,
+          success: true, resource: resource_info
+        )
+      rescue StandardError => e
+        Models::ContainerOperationResult.new(
+          container: source_ct, operation: :clone,
+          success: :partial, resource: resource_info,
+          error: "Cloned successfully, but config update failed: #{e.message}"
+        )
+      end
+
+      # Builds Proxmox API parameters from user-friendly container config options.
+      #
+      # Maps config keys to their Proxmox API equivalents. Does not include
+      # hostname, ostemplate, description, or pool (those belong to the clone step).
+      #
+      # @param config_params [Hash] User-friendly config parameters
+      # @return [Hash] Proxmox API parameters
+      def build_ct_config_api_params(config_params)
+        params = {}
+        params[:cores] = config_params[:cores] if config_params[:cores]
+        params[:memory] = config_params[:memory] if config_params[:memory]
+        params[:swap] = config_params[:swap] if config_params[:swap]
+        params[:unprivileged] = config_params[:privileged] ? 0 : 1 unless config_params[:privileged].nil?
+        params[:rootfs] = Parsers::LxcMountConfig.to_proxmox(config_params[:rootfs]) if config_params[:rootfs]
+        add_mountpoint_params(params, config_params[:mountpoints]) if config_params[:mountpoints]
+        add_net_params(params, config_params[:nets]) if config_params[:nets]
+        params[:features] = config_params[:features] if config_params[:features]
+        params[:password] = config_params[:password] if config_params[:password]
+        params[:"ssh-public-keys"] = config_params[:ssh_public_keys] if config_params[:ssh_public_keys]
+        params[:onboot] = config_params[:onboot] ? 1 : 0 unless config_params[:onboot].nil?
+        params[:startup] = config_params[:startup] if config_params[:startup]
+        params[:tags] = config_params[:tags] if config_params[:tags]
+        params
+      end
+
+      # Adds mountpoint parameters mapped to mp0, mp1, etc.
+      #
+      # @param params [Hash] Parameters hash to modify
+      # @param mountpoints [Array<Hash>] Mountpoint configurations
+      # @return [void]
+      def add_mountpoint_params(params, mountpoints)
+        mountpoints.each_with_index do |mp, index|
+          params[:"mp#{index}"] = Parsers::LxcMountConfig.to_proxmox(mp)
+        end
+      end
+
+      # Adds network parameters mapped to net0, net1, etc.
+      #
+      # @param params [Hash] Parameters hash to modify
+      # @param nets [Array<Hash>] Network configurations
+      # @return [void]
+      def add_net_params(params, nets)
+        nets.each_with_index do |net, index|
+          params[:"net#{index}"] = Parsers::LxcNetConfig.to_proxmox(net)
+        end
+      end
+
+      # Starts a container after successful clone and config update.
+      #
+      # @param ctid [Integer] Container identifier
+      # @param node [String] Node name
+      # @return [void]
+      def start_container(ctid, node)
+        upid = @container_repository.start(ctid, node)
+        @task_repository.wait(upid, timeout: START_TIMEOUT)
+      end
+
+      # Returns configured timeout.
+      #
+      # @return [Integer] Timeout in seconds
+      def timeout
+        @options[:timeout] || DEFAULT_TIMEOUT
+      end
+
+      # Returns error for container not found.
+      #
+      # @param ctid [Integer] Container identifier
+      # @return [Models::ContainerOperationResult] Failed result
+      def container_not_found_error(ctid)
+        Models::ContainerOperationResult.new(
+          operation: :clone,
+          success: false,
+          error: "Container #{ctid} not found"
+        )
+      end
+
+      # Returns error for linked clone of non-template container.
+      #
+      # @param source_ct [Models::Container] Source container
+      # @return [Models::ContainerOperationResult] Failed result
+      def linked_clone_error(source_ct)
+        Models::ContainerOperationResult.new(
+          container: source_ct, operation: :clone,
+          success: false,
+          error: "Linked clone requires container to be a template. Container #{source_ct.vmid} is not a template"
+        )
+      end
+    end
+  end
+end