pvectl 0.2.0

data/lib/pvectl/services/set_volume.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates non-interactive volume property updates.
+    #
+    # Handles two types of changes:
+    # 1. Size changes — delegates to ResizeVolume service (irreversible)
+    # 2. Config changes (cache, discard, ssd, etc.) — rebuilds volume config string
+    #
+    # @example Resize only
+    #   service = SetVolume.new(repository: vm_repo, resource_type: :vm)
+    #   result = service.execute(id: 100, disk: "scsi0", params: { "size" => "+10G" }, node: "pve1")
+    #
+    # @example Config change
+    #   service.execute(id: 100, disk: "scsi0", params: { "cache" => "writeback" }, node: "pve1")
+    #
+    # @example Mixed (size + config)
+    #   service.execute(id: 100, disk: "scsi0",
+    #     params: { "size" => "+10G", "cache" => "writeback" }, node: "pve1")
+    #
+    class SetVolume
+      # @param repository [Repositories::Vm, Repositories::Container] resource repository
+      # @param resource_type [Symbol] :vm or :container
+      def initialize(repository:, resource_type:)
+        @repository = repository
+        @resource_type = resource_type
+      end
+
+      # Executes the volume property update.
+      #
+      # Separates size param (delegated to ResizeVolume) from config params
+      # (rebuilt into the disk config string). Both can be applied in a single call.
+      #
+      # @param id [Integer] resource ID (VMID or CTID)
+      # @param disk [String] disk name (e.g., "scsi0", "rootfs")
+      # @param params [Hash] key-value pairs to set
+      # @param node [String] node name
+      # @return [Models::VolumeOperationResult] operation result
+      def execute(id:, disk:, params:, node:)
+        config = @repository.fetch_config(node, id)
+        disk_value = config[disk.to_sym]
+
+        unless disk_value
+          return build_result(id, disk, node, success: false,
+                              error: "Volume '#{disk}' not found in config for resource #{id}")
+        end
+
+        # Separate size from config params (dup to avoid mutating caller's hash)
+        params = params.dup
+        size_param = params.delete("size") || params.delete(:size)
+        config_params = params
+
+        # Handle size change (resize)
+        if size_param
+          parsed_size = ResizeVolume.parse_size(size_param)
+          resize_service = ResizeVolume.new(repository: @repository)
+          resize_service.preflight(id, disk, parsed_size, node: node)
+          resize_service.perform(id, disk, parsed_size.raw, node: node)
+        end
+
+        # Handle config changes (cache, discard, ssd, iothread, backup)
+        unless config_params.empty?
+          new_disk_value = rebuild_disk_config(disk_value, config_params)
+          @repository.update(id, node, { disk.to_sym => new_disk_value })
+        end
+
+        build_result(id, disk, node, success: true)
+      rescue ResizeVolume::VolumeNotFoundError, ResizeVolume::SizeTooSmallError, ArgumentError => e
+        build_result(id, disk, node, success: false, error: e.message)
+      rescue StandardError => e
+        build_result(id, disk, node, success: false, error: e.message)
+      end
+
+      private
+
+      # Rebuilds a disk config string with updated properties.
+      #
+      # Config format: "storage:volume-id,key1=val1,key2=val2"
+      # Replaces existing keys and appends new ones.
+      #
+      # @param current_value [String] current disk config string
+      # @param updates [Hash] key-value pairs to update
+      # @return [String] updated config string
+      def rebuild_disk_config(current_value, updates)
+        parts = current_value.to_s.split(",")
+        base = parts.shift # "storage:volume-id"
+
+        # Parse existing key=value pairs
+        existing = {}
+        parts.each do |part|
+          key, value = part.split("=", 2)
+          existing[key] = value
+        end
+
+        # Apply updates
+        updates.each do |key, value|
+          existing[key.to_s] = value.to_s
+        end
+
+        # Rebuild string
+        config_parts = existing.map { |k, v| "#{k}=#{v}" }
+        ([base] + config_parts).join(",")
+      end
+
+      # Builds a VolumeOperationResult with volume metadata.
+      #
+      # @param id [Integer] resource ID
+      # @param disk [String] disk name
+      # @param node [String] node name
+      # @param attrs [Hash] result attributes (:success, :error)
+      # @return [Models::VolumeOperationResult]
+      def build_result(id, disk, node, **attrs)
+        volume = Models::Volume.new(
+          name: disk,
+          resource_type: @resource_type.to_s,
+          resource_id: id,
+          node: node
+        )
+        Models::VolumeOperationResult.new(
+          operation: :set, volume: volume, **attrs
+        )
+      end
+    end
+  end
+end

data/lib/pvectl/services/snapshot.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates snapshot operations.
+    #
+    # Handles listing, creating, deleting and rolling back snapshots
+    # for VMs and containers with unified interface.
+    #
+    # @example Basic usage
+    #   service = Snapshot.new(
+    #     snapshot_repo: snapshot_repo,
+    #     resource_resolver: resolver,
+    #     task_repo: task_repo
+    #   )
+    #   snapshots = service.list([100, 101])
+    #
+    class Snapshot
+      DEFAULT_TIMEOUT = 60
+
+      # Creates a new Snapshot service.
+      #
+      # @param snapshot_repo [Repositories::Snapshot] Snapshot 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(snapshot_repo:, resource_resolver:, task_repo:, options: {})
+        @snapshot_repo = snapshot_repo
+        @resolver = resource_resolver
+        @task_repo = task_repo
+        @options = options
+      end
+
+      # Lists snapshots for given VMIDs.
+      #
+      # When vmids is empty, lists snapshots for all resources in the cluster.
+      #
+      # @param vmids [Array<Integer>] VM/container IDs (empty = all)
+      # @param node [String, nil] filter by node name
+      # @return [Array<Models::Snapshot>] all snapshots
+      def list(vmids, node: nil)
+        resources = resolve_resources(vmids)
+        resources = filter_by_node(resources, node)
+        return [] if resources.empty?
+
+        resources.flat_map do |r|
+          @snapshot_repo.list(r[:vmid], r[:node], r[:type])
+        end
+      end
+
+      # Describes a snapshot by name across given VMIDs.
+      #
+      # When vmids is empty, searches all resources in the cluster.
+      # Returns a SnapshotDescription with entries for each VM/CT that has the snapshot.
+      #
+      # @param vmids [Array<Integer>] VM/container IDs (empty = search all)
+      # @param name [String] snapshot name to find
+      # @param node [String, nil] filter by node name
+      # @return [Models::SnapshotDescription] description with entries per VM
+      # @raise [ResourceNotFoundError] when snapshot not found
+      def describe(vmids, name, node: nil)
+        resources = resolve_resources(vmids)
+        resources = filter_by_node(resources, node)
+
+        if resources.empty?
+          message = vmids.empty? ? "no resources found in cluster" : "resource #{vmids.first} not found"
+          raise ResourceNotFoundError, message
+        end
+
+        entries = build_describe_entries(resources, name)
+
+        if entries.empty?
+          message = vmids.empty? ? "snapshot '#{name}' not found in cluster" : "snapshot '#{name}' not found on VM #{vmids.join(', ')}"
+          raise ResourceNotFoundError, message
+        end
+
+        Models::SnapshotDescription.new(entries: entries)
+      end
+
+      # Creates snapshots for given VMIDs, or all cluster resources when vmids is empty.
+      #
+      # When vmids is empty, creates snapshots for all resources in the cluster.
+      #
+      # @param vmids [Array<Integer>] VM/container IDs (empty = all)
+      # @param name [String] snapshot name
+      # @param description [String, nil] optional description
+      # @param vmstate [Boolean] save VM memory state
+      # @param node [String, nil] filter by node name
+      # @return [Array<Models::OperationResult>] results for each resource
+      def create(vmids, name:, description: nil, vmstate: false, node: nil)
+        resources = resolve_resources(vmids)
+        resources = filter_by_node(resources, node)
+        return [] if resources.empty?
+
+        execute_multi(resources, :create) do |r|
+          @snapshot_repo.create(r[:vmid], r[:node], r[:type], name: name, description: description, vmstate: vmstate)
+        end
+      end
+
+      # Deletes snapshots from given VMIDs, or all cluster resources when vmids is empty.
+      #
+      # When vmids is empty, deletes snapshots from all resources in the cluster.
+      #
+      # @param vmids [Array<Integer>] VM/container IDs (empty = all)
+      # @param snapname [String] snapshot name to delete
+      # @param force [Boolean] force removal even if disk snapshot fails
+      # @param node [String, nil] filter by node name
+      # @return [Array<Models::OperationResult>] results for each resource
+      def delete(vmids, snapname, force: false, node: nil)
+        resources = resolve_resources(vmids)
+        resources = filter_by_node(resources, node)
+        return [] if resources.empty?
+
+        execute_multi(resources, :delete) do |r|
+          @snapshot_repo.delete(r[:vmid], r[:node], r[:type], snapname, force: force)
+        end
+      end
+
+      # Deletes ALL snapshots from given VMIDs.
+      #
+      # When vmids is empty, deletes all snapshots from all resources in the cluster.
+      # Skips the "current" pseudo-snapshot.
+      #
+      # @param vmids [Array<Integer>] VM/container IDs (empty = all)
+      # @param node [String, nil] filter by node name
+      # @param force [Boolean] force removal even if disk snapshot fails
+      # @return [Array<Models::OperationResult>] results for each snapshot
+      def delete_all(vmids, node: nil, force: false)
+        resources = resolve_resources(vmids)
+        resources = filter_by_node(resources, node)
+        return [] if resources.empty?
+
+        results = []
+
+        resources.each do |r|
+          snapshots = @snapshot_repo.list(r[:vmid], r[:node], r[:type])
+          snapshots.reject! { |s| s.name == "current" }
+
+          snapshots.each do |snap|
+            result = execute_single(r, :delete) do
+              @snapshot_repo.delete(r[:vmid], r[:node], r[:type], snap.name, force: force)
+            end
+            results << result
+
+            break if @options[:fail_fast] && result.failed?
+          end
+
+          break if @options[:fail_fast] && results.last&.failed?
+        end
+
+        results
+      end
+
+      # Rolls back to a snapshot.
+      #
+      # @param vmid [Integer] VM/container ID
+      # @param snapname [String] snapshot name to rollback to
+      # @param start [Boolean] start after rollback (LXC only)
+      # @return [Models::OperationResult] result
+      def rollback(vmid, snapname, start: false)
+        resource = @resolver.resolve(vmid)
+
+        if resource.nil?
+          return Models::OperationResult.new(
+            resource: { vmid: vmid },
+            operation: :rollback,
+            success: false,
+            error: "Resource #{vmid} not found"
+          )
+        end
+
+        execute_single(resource, :rollback) do
+          @snapshot_repo.rollback(resource[:vmid], resource[:node], resource[:type], snapname, start: start)
+        end
+      end
+
+      private
+
+      # Resolves resources from VMIDs or returns all cluster resources.
+      #
+      # @param vmids [Array<Integer>] VM/container IDs (empty = resolve all)
+      # @return [Array<Hash>] resolved resources
+      def resolve_resources(vmids)
+        vmids.empty? ? @resolver.resolve_all : @resolver.resolve_multiple(vmids)
+      end
+
+      # Filters resources by node name.
+      #
+      # @param resources [Array<Hash>] resolved resources
+      # @param node [String, nil] node name to filter by (nil = no filter)
+      # @return [Array<Hash>] filtered resources
+      def filter_by_node(resources, node)
+        return resources unless node
+
+        resources.select { |r| r[:node] == node }
+      end
+
+      def build_describe_entries(resources, name)
+        entries = []
+
+        resources.each do |r|
+          siblings = @snapshot_repo.list(r[:vmid], r[:node], r[:type])
+          target = siblings.find { |s| s.name == name }
+          next unless target
+
+          entries << Models::SnapshotDescription::Entry.new(
+            snapshot: target,
+            siblings: siblings
+          )
+        end
+
+        entries
+      end
+
+      def execute_multi(resources, operation)
+        results = []
+
+        resources.each do |r|
+          result = execute_single(r, operation) { yield(r) }
+          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
+    end
+  end
+end

data/lib/pvectl/services/task_listing.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Service for listing tasks across one or all cluster nodes.
+    #
+    # Encapsulates multi-node iteration, merge, sort, and limit logic.
+    # Used by both Get::Handlers::Tasks and Logs::Handlers::TaskLogs.
+    #
+    # @example List all tasks cluster-wide
+    #   service = TaskListing.new(task_list_repository: repo, node_repository: node_repo)
+    #   tasks = service.list(limit: 20)
+    #
+    # @example List tasks on a specific node
+    #   tasks = service.list(node: "pve1", type_filter: "vzdump")
+    #
+    class TaskListing
+      # Creates a new TaskListing service.
+      #
+      # @param task_list_repository [Repositories::TaskList] task list repository
+      # @param node_repository [Repositories::Node] node repository for cluster discovery
+      def initialize(task_list_repository:, node_repository:)
+        @task_list_repository = task_list_repository
+        @node_repository = node_repository
+      end
+
+      # Lists tasks, optionally filtered.
+      #
+      # When node is nil, iterates all cluster nodes and merges results
+      # sorted by starttime descending.
+      #
+      # @param node [String, nil] specific node or nil for all nodes
+      # @param vmid [Integer, nil] filter by VMID
+      # @param limit [Integer] max entries (default 50)
+      # @param since [String, nil] start time filter
+      # @param until_time [String, nil] end time filter
+      # @param type_filter [String, nil] task type filter
+      # @param status_filter [String, nil] status filter
+      # @return [Array<Models::TaskEntry>] task entries
+      def list(node: nil, vmid: nil, limit: 50, since: nil, until_time: nil,
+               type_filter: nil, status_filter: nil)
+        if node
+          @task_list_repository.list(
+            node: node, vmid: vmid, limit: limit, since: since,
+            until_time: until_time, type_filter: type_filter,
+            status_filter: status_filter
+          )
+        else
+          list_all_nodes(
+            vmid: vmid, limit: limit, since: since,
+            until_time: until_time, type_filter: type_filter,
+            status_filter: status_filter
+          )
+        end
+      end
+
+      private
+
+      # Iterates all cluster nodes and merges results.
+      #
+      # @return [Array<Models::TaskEntry>] merged and sorted entries
+      def list_all_nodes(vmid:, limit:, since:, until_time:, type_filter:, status_filter:)
+        nodes = @node_repository.list.map(&:name)
+        entries = nodes.flat_map do |node_name|
+          @task_list_repository.list(
+            node: node_name, vmid: vmid, limit: limit, since: since,
+            until_time: until_time, type_filter: type_filter,
+            status_filter: status_filter
+          )
+        end
+        entries.sort_by { |e| -(e.starttime || 0) }.first(limit)
+      end
+    end
+  end
+end

data/lib/pvectl/services/unlink_disk.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates disk unlinking from a VM configuration.
+    #
+    # Delegates to the VM repository to issue the unlink PUT request and
+    # wraps the outcome in a {Models::VmOperationResult}. The underlying
+    # Proxmox endpoint is synchronous and returns no UPID, so the result
+    # captures success/failure synchronously.
+    #
+    # @example Soft unlink (keeps volume as unused[n])
+    #   service = UnlinkDisk.new(repository: vm_repo)
+    #   result = service.execute(vmid: 100, node: "pve1", disk_ids: "scsi1")
+    #
+    # @example Hard delete via force
+    #   service = UnlinkDisk.new(repository: vm_repo)
+    #   result = service.execute(vmid: 100, node: "pve1", disk_ids: %w[scsi1 scsi2], force: true)
+    #
+    class UnlinkDisk
+      # Creates a new UnlinkDisk service.
+      #
+      # @param repository [Repositories::Vm] VM repository
+      def initialize(repository:)
+        @repository = repository
+      end
+
+      # Unlinks one or more disks from the VM configuration.
+      #
+      # @param vmid [Integer] VM identifier
+      # @param node [String] node name
+      # @param disk_ids [Array<String>, String] disk identifiers
+      # @param force [Boolean] physically remove the underlying volume(s)
+      # @return [Models::VmOperationResult] operation result
+      def execute(vmid:, node:, disk_ids:, force: false)
+        @repository.unlink_disks(node, vmid, disk_ids, force: force)
+        build_result(vmid, node, disk_ids, force, success: true)
+      rescue StandardError => e
+        build_result(vmid, node, disk_ids, force, success: false, error: e.message)
+      end
+
+      private
+
+      # Builds a VmOperationResult.
+      #
+      # @param vmid [Integer] VM identifier
+      # @param node [String] node name
+      # @param disk_ids [Array<String>, String] disk identifiers
+      # @param force [Boolean] force flag
+      # @param attrs [Hash] additional result attributes (:success, :error)
+      # @return [Models::VmOperationResult]
+      def build_result(vmid, node, disk_ids, force, **attrs)
+        vm = fetch_vm(vmid) || Models::Vm.new(vmid: vmid, node: node)
+        Models::VmOperationResult.new(
+          operation: :unlink_disk,
+          vm: vm,
+          resource: {
+            vmid: vmid,
+            node: node,
+            disk_ids: format_disk_ids(disk_ids),
+            force: force
+          },
+          **attrs
+        )
+      end
+
+      # Fetches the VM model for the result, swallowing any lookup errors.
+      #
+      # @param vmid [Integer] VM identifier
+      # @return [Models::Vm, nil] VM model or nil if unavailable
+      def fetch_vm(vmid)
+        @repository.get(vmid)
+      rescue StandardError
+        nil
+      end
+
+      # Formats disk_ids into a stable comma-separated representation.
+      #
+      # @param disk_ids [Array<String>, String] disk identifiers
+      # @return [String] comma-separated disk ID list
+      def format_disk_ids(disk_ids)
+        Array(disk_ids).flat_map { |id| id.to_s.split(",") }.map(&:strip).reject(&:empty?).join(",")
+      end
+    end
+  end
+end

data/lib/pvectl/services/vm_lifecycle.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates VM lifecycle operations.
+    #
+    # Handles execution of start/stop/shutdown/restart/reset/suspend/resume
+    # operations with sync/async modes, error handling, and result collection.
+    #
+    # @example Basic usage
+    #   service = VmLifecycle.new(vm_repo, task_repo)
+    #   results = service.execute(:start, [vm1, vm2])
+    #   results.each { |r| puts "#{r.vm.vmid}: #{r.status_text}" }
+    #
+    class VmLifecycle
+      SYNC_OPERATIONS = %i[start stop reset resume].freeze
+      ASYNC_OPERATIONS = %i[shutdown restart suspend].freeze
+      ALL_OPERATIONS = (SYNC_OPERATIONS + ASYNC_OPERATIONS).freeze
+
+      DEFAULT_TIMEOUT = 60
+
+      # Creates a new VmLifecycle service.
+      #
+      # @param vm_repository [Repositories::Vm] VM repository
+      # @param task_repository [Repositories::Task] Task repository
+      # @param options [Hash] Options (timeout, async, wait, fail_fast)
+      def initialize(vm_repository, task_repository, options = {})
+        @vm_repository = vm_repository
+        @task_repository = task_repository
+        @options = options
+      end
+
+      # Executes a lifecycle operation on a list of VMs.
+      #
+      # @param operation [Symbol] Operation to execute
+      # @param vms [Array<Models::Vm>] VMs to operate on
+      # @return [Array<Models::OperationResult>] Results for each VM
+      def execute(operation, vms)
+        validate_operation!(operation)
+
+        results = []
+        vms.each do |vm|
+          result = execute_single(operation, vm)
+          results << result
+
+          break if @options[:fail_fast] && result.failed?
+        end
+        results
+      end
+
+      private
+
+      # Executes operation on a single VM.
+      #
+      # @param operation [Symbol] Operation
+      # @param vm [Models::Vm] VM
+      # @return [Models::OperationResult] Result
+      def execute_single(operation, vm)
+        task_upid = call_api(operation, vm)
+
+        if sync_mode?(operation)
+          task = @task_repository.wait(task_upid, timeout: timeout)
+          Models::VmOperationResult.new(
+            vm: vm,
+            operation: operation,
+            task: task,
+            success: task.successful?
+          )
+        else
+          Models::VmOperationResult.new(
+            vm: vm,
+            operation: operation,
+            task_upid: task_upid,
+            success: :pending
+          )
+        end
+      rescue StandardError => e
+        Models::VmOperationResult.new(
+          vm: vm,
+          operation: operation,
+          success: false,
+          error: e.message
+        )
+      end
+
+      # Calls the appropriate API method.
+      #
+      # @param operation [Symbol] Operation
+      # @param vm [Models::Vm] VM
+      # @return [String] Task UPID
+      def call_api(operation, vm)
+        @vm_repository.send(operation, vm.vmid, vm.node)
+      end
+
+      # Determines if operation should run in sync mode.
+      #
+      # @param operation [Symbol] Operation
+      # @return [Boolean] true if sync mode
+      def sync_mode?(operation)
+        return false if @options[:async]
+        return true if @options[:wait]
+
+        SYNC_OPERATIONS.include?(operation)
+      end
+
+      # Returns configured timeout.
+      #
+      # @return [Integer] Timeout in seconds
+      def timeout
+        @options[:timeout] || DEFAULT_TIMEOUT
+      end
+
+      # Validates operation is supported.
+      #
+      # @param operation [Symbol] Operation
+      # @raise [ArgumentError] if operation is not supported
+      def validate_operation!(operation)
+        return if ALL_OPERATIONS.include?(operation)
+
+        raise ArgumentError, "Unknown operation: #{operation}. Valid: #{ALL_OPERATIONS.join(', ')}"
+      end
+    end
+  end
+end