pvectl 0.2.0

data/lib/pvectl/presenters/vm_operation_result.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Presenters
+    # Presenter for VM lifecycle operation results.
+    #
+    # Formats VmOperationResult models for table/JSON/YAML output.
+    #
+    # @example Using with formatter
+    #   presenter = VmOperationResult.new
+    #   formatter = Formatters::Table.new
+    #   output = formatter.format(results, presenter)
+    #
+    class VmOperationResult < OperationResult
+      # Returns column headers for standard table output.
+      #
+      # @return [Array<String>] column headers
+      def columns
+        %w[VMID NAME NODE STATUS MESSAGE]
+      end
+
+      # Returns additional columns for wide output.
+      #
+      # @return [Array<String>] extra column headers
+      def extra_columns
+        %w[TASK DURATION]
+      end
+
+      # Converts result to table row values.
+      #
+      # For clone operations, displays the new (cloned) VM data.
+      # For all other operations, displays the source VM data.
+      #
+      # @param model [Models::VmOperationResult] result model
+      # @param context [Hash] optional context
+      # @return [Array<String>] row values
+      def to_row(model, **_context)
+        if model.operation == :clone && model.resource
+          [
+            model.resource[:new_vmid].to_s,
+            model.resource[:name] || "VM-#{model.resource[:new_vmid]}",
+            model.resource[:node] || model.vm&.node,
+            status_display(model),
+            model.message
+          ]
+        else
+          [
+            model.vm.vmid.to_s,
+            display_name(model.vm),
+            model.vm.node,
+            status_display(model),
+            model.message
+          ]
+        end
+      end
+
+      # Returns additional values for wide output.
+      #
+      # @param model [Models::VmOperationResult] result model
+      # @param context [Hash] optional context
+      # @return [Array<String>] extra values
+      def extra_values(model, **_context)
+        [
+          task_upid(model),
+          duration_display(model)
+        ]
+      end
+
+      # Converts result to hash for JSON/YAML output.
+      #
+      # For clone operations, displays the new (cloned) VM data.
+      # For all other operations, displays the source VM data.
+      #
+      # @param model [Models::VmOperationResult] result model
+      # @return [Hash] hash representation
+      def to_hash(model)
+        if model.operation == :clone && model.resource
+          {
+            "vmid" => model.resource[:new_vmid],
+            "name" => model.resource[:name],
+            "node" => model.resource[:node] || model.vm&.node,
+            "status" => model.status_text,
+            "message" => model.message,
+            "task_upid" => model.task_upid || model.task&.upid
+          }
+        else
+          {
+            "vmid" => model.vm.vmid,
+            "name" => model.vm.name,
+            "node" => model.vm.node,
+            "status" => model.status_text,
+            "message" => model.message,
+            "task_upid" => model.task_upid || model.task&.upid
+          }
+        end
+      end
+
+      private
+
+      # Returns display name for VM.
+      #
+      # @param vm [Models::Vm] VM model
+      # @return [String] display name
+      def display_name(vm)
+        vm.name || "VM-#{vm.vmid}"
+      end
+    end
+  end
+end

data/lib/pvectl/presenters/volume.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Presenters
+    # Presenter for virtual disks (volumes) attached to VMs and containers.
+    #
+    # Defines column layout and formatting for table output.
+    # Standard columns show node, resource type, ID, name, storage, size, and format.
+    # Wide columns add volume ID, cache, discard, SSD, iothread, and backup flags.
+    #
+    # @example Using with formatter
+    #   presenter = Volume.new
+    #   formatter = Formatters::Table.new
+    #   output = formatter.format(volumes, presenter)
+    #
+    # @see Pvectl::Models::Volume Volume model
+    # @see Pvectl::Formatters::Table Table formatter
+    #
+    class Volume < Base
+      # Returns column headers for standard table output.
+      #
+      # @return [Array<String>] column headers
+      def columns
+        %w[NODE RESOURCE ID NAME STORAGE SIZE FORMAT]
+      end
+
+      # Returns additional column headers for wide output.
+      #
+      # @return [Array<String>] extra column headers
+      def extra_columns
+        %w[VOLUME-ID CACHE DISCARD SSD IOTHREAD BACKUP]
+      end
+
+      # Converts Volume model to table row values.
+      #
+      # @param model [Models::Volume] Volume model
+      # @param _context [Hash] optional context
+      # @return [Array<String>] row values matching columns order
+      def to_row(model, **_context)
+        @volume = model
+        [
+          volume.node || "-",
+          volume.resource_type || "-",
+          volume.resource_id&.to_s || "-",
+          volume.name || "-",
+          volume.storage || "-",
+          volume.size || "-",
+          volume.format || "-"
+        ]
+      end
+
+      # Returns additional values for wide output.
+      #
+      # @param model [Models::Volume] Volume model
+      # @param _context [Hash] optional context
+      # @return [Array<String>] extra values matching extra_columns order
+      def extra_values(model, **_context)
+        @volume = model
+        [
+          volume.volume_id || "-",
+          volume.cache || "-",
+          volume.discard || "-",
+          volume.ssd&.to_s || "-",
+          volume.iothread&.to_s || "-",
+          volume.backup&.to_s || "-"
+        ]
+      end
+
+      # Converts Volume model to hash for JSON/YAML output.
+      #
+      # @param model [Models::Volume] Volume model
+      # @return [Hash{String => untyped}] hash representation with string keys
+      def to_hash(model)
+        @volume = model
+        {
+          "name" => volume.name,
+          "storage" => volume.storage,
+          "volume_id" => volume.volume_id,
+          "volid" => volume.volid,
+          "size" => volume.size,
+          "format" => volume.format,
+          "resource_type" => volume.resource_type,
+          "resource_id" => volume.resource_id,
+          "node" => volume.node,
+          "content" => volume.content,
+          "cache" => volume.cache,
+          "discard" => volume.discard,
+          "ssd" => volume.ssd,
+          "iothread" => volume.iothread,
+          "backup" => volume.backup,
+          "mp" => volume.mp
+        }
+      end
+
+      # Returns detailed description for describe command output.
+      #
+      # @param model [Models::Volume] Volume model
+      # @return [Hash{String => Hash{String, String}}] nested hash with Volume Info section
+      def to_description(model)
+        @volume = model
+        { "Volume Info" => volume_info_section }
+      end
+
+      private
+
+      # @return [Models::Volume] the current volume being presented
+      attr_reader :volume
+
+      # Builds the Volume Info section hash.
+      # Optional fields are only included when they have values.
+      #
+      # @return [Hash{String => String}] volume info key-value pairs
+      def volume_info_section
+        info = {
+          "Name" => volume.name || "-",
+          "Storage" => volume.storage || "-",
+          "Volume ID" => volume.volume_id || "-",
+          "Full Volume ID" => volume.volid || "-",
+          "Size" => volume.size || "-",
+          "Format" => volume.format || "-",
+          "Resource Type" => volume.resource_type || "-",
+          "Resource ID" => volume.resource_id&.to_s || "-",
+          "Node" => volume.node || "-"
+        }
+        info["Content"] = volume.content if volume.content
+        info["Cache"] = volume.cache if volume.cache
+        info["Discard"] = volume.discard if volume.discard
+        info["SSD"] = volume.ssd if volume.ssd
+        info["IO Thread"] = volume.iothread if volume.iothread
+        info["Backup"] = volume.backup if volume.backup
+        info["Mount Point"] = volume.mp if volume.mp
+        info
+      end
+    end
+  end
+end

data/lib/pvectl/presenters/volume_operation_result.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Presenters
+    # Presenter for volume operation results (set/edit).
+    #
+    # Formats VolumeOperationResult models for table/JSON/YAML output.
+    #
+    # @example Using with formatter
+    #   presenter = VolumeOperationResult.new
+    #   formatter = Formatters::Table.new
+    #   output = formatter.format(results, presenter)
+    #
+    class VolumeOperationResult < OperationResult
+      # Returns column headers for standard table output.
+      #
+      # @return [Array<String>] column headers
+      def columns
+        %w[NODE RESOURCE ID DISK OPERATION STATUS MESSAGE]
+      end
+
+      # Converts result to table row values.
+      #
+      # @param model [Models::VolumeOperationResult] result model
+      # @param context [Hash] optional context
+      # @return [Array<String>] row values
+      def to_row(model, **_context)
+        vol = model.volume
+        [
+          vol&.node || "-",
+          vol&.resource_type || "-",
+          vol&.resource_id&.to_s || "-",
+          vol&.name || "-",
+          model.operation&.to_s || "-",
+          status_display(model),
+          model.message
+        ]
+      end
+
+      # Converts result to hash for JSON/YAML output.
+      #
+      # @param model [Models::VolumeOperationResult] result model
+      # @return [Hash] hash representation
+      def to_hash(model)
+        vol = model.volume
+        {
+          "node" => vol&.node,
+          "resource_type" => vol&.resource_type,
+          "resource_id" => vol&.resource_id,
+          "disk" => vol&.name,
+          "operation" => model.operation&.to_s,
+          "status" => model.status_text,
+          "message" => model.message
+        }
+      end
+    end
+  end
+end

data/lib/pvectl/repositories/apt.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Repositories
+    # Repository for Proxmox APT package management on cluster nodes.
+    #
+    # Wraps the `/nodes/{node}/apt/*` API endpoints. Provides:
+    # - listing pending package updates (GET /apt/update)
+    # - refreshing the package index (POST /apt/update — apt-get update)
+    # - reading per-package changelogs (GET /apt/changelog)
+    # - listing important Proxmox package versions (GET /apt/versions)
+    #
+    # @example Listing pending updates on a node
+    #   repo = Apt.new(connection)
+    #   updates = repo.pending("pve1")
+    #   updates.each { |p| puts "#{p.package}: #{p.old_version} -> #{p.version}" }
+    #
+    # @example Triggering a package index refresh
+    #   upid = repo.refresh("pve1", notify: false, quiet: true)
+    #
+    # @see Pvectl::Models::AptPackage AptPackage model
+    # @see Pvectl::Connection API connection
+    #
+    class Apt < Base
+      # Lists pending APT updates available on a node.
+      #
+      # @param node [String] node name
+      # @return [Array<Models::AptPackage>] pending package updates
+      def pending(node)
+        response = connection.client["nodes/#{node}/apt/update"].get
+        packages = unwrap(response)
+        packages.map { |data| build_model(data.merge(node: node)) }
+      rescue StandardError
+        []
+      end
+
+      # Refreshes the package index on a node (equivalent to apt-get update).
+      #
+      # Returns the Proxmox task UPID — the operation runs asynchronously.
+      #
+      # @param node [String] node name
+      # @param notify [Boolean] whether to send a notification about new packages
+      # @param quiet [Boolean] whether to suppress progress output
+      # @return [String] task UPID
+      def refresh(node, notify: false, quiet: false)
+        params = {}
+        params[:notify] = 1 if notify
+        params[:quiet] = 1 if quiet
+        response = connection.client["nodes/#{node}/apt/update"].post(params)
+        data = extract_data(response)
+        data.is_a?(String) ? data : data.to_s
+      end
+
+      # Fetches the changelog for a package on a node.
+      #
+      # @param node [String] node name
+      # @param package [String] package name
+      # @param version [String, nil] specific package version (optional)
+      # @return [String] changelog text (empty string on error)
+      def changelog(node, package, version: nil)
+        params = { name: package }
+        params[:version] = version if version
+        response = connection.client["nodes/#{node}/apt/changelog"].get(params: params)
+        data = extract_data(response)
+        data.is_a?(String) ? data : data.to_s
+      rescue StandardError
+        ""
+      end
+
+      # Lists important Proxmox package versions installed on a node.
+      #
+      # @param node [String] node name
+      # @return [Array<Models::AptPackage>] installed package versions
+      def versions(node)
+        response = connection.client["nodes/#{node}/apt/versions"].get
+        packages = unwrap(response)
+        packages.map { |data| build_model(data.merge(node: node)) }
+      rescue StandardError
+        []
+      end
+
+      protected
+
+      # Builds AptPackage model from API response data.
+      #
+      # @param data [Hash] API response hash
+      # @return [Models::AptPackage] AptPackage model instance
+      def build_model(data)
+        Models::AptPackage.new(data)
+      end
+    end
+  end
+end

data/lib/pvectl/repositories/backup.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Pvectl
+  module Repositories
+    # Repository for backup operations in Proxmox.
+    #
+    # Handles listing, creating, deleting, and restoring backups
+    # via the Proxmox API (vzdump).
+    #
+    # @example Listing backups
+    #   repo = Backup.new(connection)
+    #   backups = repo.list(node: "pve1", storage: "local")
+    #
+    # @example Creating a backup
+    #   upid = repo.create(100, "pve1", storage: "local", mode: "snapshot")
+    #
+    # @example Restoring a backup
+    #   upid = repo.restore("local:backup/vzdump-qemu-100.vma.zst", "pve1", vmid: 200)
+    #
+    # @see Pvectl::Models::Backup Backup model
+    # @see Pvectl::Connection API connection
+    #
+    class Backup < Base
+      # Lists backups from storage.
+      #
+      # When node and storage are not specified, discovers all nodes and
+      # backup-capable storages automatically.
+      #
+      # @param vmid [Integer, nil] filter by VM ID
+      # @param storage [String, nil] storage name (default: all backup storages)
+      # @param node [String, nil] node name (default: all nodes)
+      # @return [Array<Models::Backup>] backup models
+      def list(vmid: nil, storage: nil, node: nil)
+        nodes = node ? [node] : list_nodes
+        storages_by_node = storage ? Hash[nodes.map { |n| [n, [storage]] }] : nil
+
+        backups = []
+        nodes.each do |n|
+          backup_storages = storages_by_node ? storages_by_node[n] : list_backup_storages(n)
+          backup_storages.each do |s|
+            backups.concat(list_from_storage(n, s, vmid: vmid))
+          end
+        end
+        backups
+      end
+
+      # Creates a backup using vzdump.
+      #
+      # @param vmid [Integer] VM/container ID
+      # @param node [String] node name
+      # @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 from deletion
+      # @return [String] task UPID
+      def create(vmid, node, storage:, mode: "snapshot", compress: "zstd", notes: nil, protected: false)
+        params = {
+          vmid: vmid,
+          storage: storage,
+          mode: mode,
+          compress: compress
+        }
+        params[:notes] = notes if notes
+        params[:protected] = 1 if protected
+
+        connection.client["nodes/#{node}/vzdump"].post(params)
+      end
+
+      # Deletes a backup.
+      #
+      # @param volid [String] full volume ID
+      # @param node [String] node name
+      # @return [String, nil] task UPID or nil
+      def delete(volid, node)
+        storage = parse_storage(volid)
+        encoded_volid = ERB::Util.url_encode(volid)
+        connection.client["nodes/#{node}/storage/#{storage}/content/#{encoded_volid}"].delete
+      end
+
+      # Restores a backup to a new or existing VM/container.
+      #
+      # @param volid [String] backup volume ID
+      # @param node [String] node name
+      # @param vmid [Integer] target VM ID
+      # @param storage [String, nil] target storage
+      # @param force [Boolean] overwrite existing VM
+      # @param start [Boolean] start after restore
+      # @param unique [Boolean] regenerate unique properties
+      # @return [String] task UPID
+      def restore(volid, node, vmid:, storage: nil, force: false, start: false, unique: false)
+        resource_type = detect_type_from_volid(volid)
+        endpoint = resource_type == :lxc ? "lxc" : "qemu"
+
+        params = {
+          archive: volid,
+          vmid: vmid
+        }
+        params[:storage] = storage if storage
+        params[:force] = 1 if force
+        params[:start] = 1 if start
+        params[:unique] = 1 if unique
+
+        connection.client["nodes/#{node}/#{endpoint}"].post(params)
+      end
+
+      private
+
+      # Lists all nodes in the cluster.
+      #
+      # @return [Array<String>] node names
+      def list_nodes
+        response = connection.client["nodes"].get
+        response.map { |n| n[:node] || n["node"] }
+      end
+
+      # Lists storages that support backup content on a node.
+      #
+      # @param node [String] node name
+      # @return [Array<String>] storage names with backup capability
+      def list_backup_storages(node)
+        response = connection.client["nodes/#{node}/storage"].get
+        response.select do |s|
+          content = s[:content] || s["content"] || ""
+          content.include?("backup")
+        end.map { |s| s[:storage] || s["storage"] }
+      end
+
+      # Lists backups from a specific storage on a node.
+      #
+      # @param node [String] node name
+      # @param storage [String] storage name
+      # @param vmid [Integer, nil] optional VM ID filter
+      # @return [Array<Models::Backup>] backup models
+      def list_from_storage(node, storage, vmid: nil)
+        response = connection.client["nodes/#{node}/storage/#{storage}/content"].get(params: { content: "backup" })
+
+        backups = response.map do |data|
+          build_backup_model(data, node, storage)
+        end
+
+        vmid ? backups.select { |b| b.vmid == vmid } : backups
+      end
+
+      # Builds a Backup model from API response data.
+      #
+      # @param data [Hash] API response hash
+      # @param node [String] node name
+      # @param storage [String] storage name
+      # @return [Models::Backup] backup model instance
+      def build_backup_model(data, node, storage)
+        Models::Backup.new(
+          volid: data[:volid] || data["volid"],
+          vmid: data[:vmid] || data["vmid"],
+          node: node,
+          storage: storage,
+          size: data[:size] || data["size"],
+          ctime: data[:ctime] || data["ctime"],
+          format: data[:format] || data["format"],
+          notes: data[:notes] || data["notes"],
+          protected: (data[:protected] || data["protected"]) == 1
+        )
+      end
+
+      # Extracts storage name from volid.
+      #
+      # @param volid [String] full volume identifier
+      # @return [String] storage name
+      def parse_storage(volid)
+        volid.split(":").first
+      end
+
+      # Detects resource type from volid pattern.
+      #
+      # @param volid [String] backup volume identifier
+      # @return [Symbol] :qemu or :lxc
+      def detect_type_from_volid(volid)
+        return :lxc if volid.include?("vzdump-lxc")
+
+        :qemu
+      end
+    end
+  end
+end

data/lib/pvectl/repositories/base.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Repositories
+    # Abstract base class for repositories.
+    #
+    # Repositories encapsulate Proxmox API communication and are responsible
+    # for converting raw API data to domain models. Each repository handles
+    # one resource type (VMs, Containers, Nodes, etc.).
+    #
+    # @abstract Subclass and implement {#list}, {#get}, and {#build_model}.
+    #
+    # @example Implementing a repository
+    #   class Vm < Base
+    #     def list(node: nil)
+    #       response = connection.client["cluster/resources"].get(params: { type: "vm" })
+    #       response.map { |data| build_model(data) }
+    #     end
+    #
+    #     def get(vmid)
+    #       list.find { |vm| vm.vmid == vmid.to_i }
+    #     end
+    #
+    #     protected
+    #
+    #     def build_model(data)
+    #       Models::Vm.new(data)
+    #     end
+    #   end
+    #
+    # @see Pvectl::Connection API connection wrapper
+    # @see Pvectl::Models::Base Model base class
+    #
+    class Base
+      # Creates repository with connection.
+      #
+      # @param connection [Connection] Proxmox API connection
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # Lists all resources.
+      #
+      # @return [Array<Models::Base>] collection of models
+      # @raise [NotImplementedError] if not implemented by subclass
+      def list
+        raise NotImplementedError, "#{self.class}#list must be implemented"
+      end
+
+      # Gets a single resource by ID.
+      #
+      # @param id [String, Integer] resource identifier
+      # @return [Models::Base, nil] model or nil if not found
+      # @raise [NotImplementedError] if not implemented by subclass
+      def get(id)
+        raise NotImplementedError, "#{self.class}#get must be implemented"
+      end
+
+      protected
+
+      # @return [Connection] the API connection
+      attr_reader :connection
+
+      # Builds model from API response data.
+      #
+      # @param data [Hash] API response hash
+      # @return [Models::Base] model instance
+      # @raise [NotImplementedError] if not implemented by subclass
+      def build_model(data)
+        raise NotImplementedError, "#{self.class}#build_model must be implemented"
+      end
+
+      # Unwraps API response to array format.
+      # Handles: Array (passthrough), Hash with :data key, Hash without :data.
+      #
+      # @param response [Array, Hash, nil] API response
+      # @return [Array] unwrapped array
+      def unwrap(response)
+        case response
+        when Array then response
+        when Hash then response[:data] || response.to_a
+        when nil then []
+        else response.to_a
+        end
+      end
+
+      # Extracts data from hash response.
+      # If response has :data key, returns its value. Otherwise returns response.
+      #
+      # @param response [Hash, Object] API response
+      # @return [Hash, Object] extracted data
+      def extract_data(response)
+        return response unless response.is_a?(Hash)
+
+        response[:data] || response
+      end
+
+      # Creates model instances from API response.
+      #
+      # @param response [Array, Hash, nil] API response (will be unwrapped)
+      # @param model_class [Class] model class to instantiate
+      # @return [Array] array of model instances
+      def models_from(response, model_class)
+        return [] if response.nil?
+
+        unwrap(response).map { |data| model_class.new(data) }
+      end
+    end
+  end
+end