pvectl 0.2.0

data/lib/pvectl/manifest_serializer.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Pvectl
+  # Wraps ConfigSerializer output with a kubectl-like manifest envelope
+  # (apiVersion, kind, metadata, spec). Handles bidirectional conversion
+  # between YAML manifest files and internal config representations.
+  module ManifestSerializer
+    API_VERSION = "pvectl/v1"
+
+    KINDS = {
+      vm: "VirtualMachine",
+      container: "Container"
+    }.freeze
+
+    KINDS_REVERSE = KINDS.invert.transform_keys(&:to_s).freeze
+
+    class << self
+      # Builds a YAML manifest string from nested config and metadata.
+      #
+      # @param nested_config [Hash] nested config from ConfigSerializer.to_nested
+      # @param type [Symbol] :vm or :container
+      # @param metadata [Hash] resource metadata (vmid, name, node, status, tags)
+      # @return [String] YAML manifest string
+      def to_yaml(nested_config, type:, metadata:)
+        manifest = {
+          "apiVersion" => API_VERSION,
+          "kind" => KINDS.fetch(type),
+          "metadata" => build_metadata(metadata),
+          "spec" => stringify_keys_deep(nested_config)
+        }
+
+        YAML.dump(manifest)
+      end
+
+      # Parses a YAML manifest string into type, metadata, and spec.
+      #
+      # @param yaml_string [String] YAML manifest
+      # @return [Hash] { type: Symbol, metadata: Hash, spec: Hash }
+      def from_yaml(yaml_string)
+        parsed = YAML.safe_load(yaml_string)
+        type = KINDS_REVERSE[parsed["kind"]]
+
+        {
+          type: type,
+          metadata: symbolize_metadata(parsed["metadata"] || {}),
+          spec: symbolize_keys_deep(parsed["spec"] || {})
+        }
+      end
+
+      # Validates manifest structure (envelope only, not spec content).
+      #
+      # @param yaml_string [String] YAML manifest
+      # @return [Array<String>] error messages (empty if valid)
+      def validate(yaml_string)
+        errors = []
+
+        begin
+          parsed = YAML.safe_load(yaml_string)
+        rescue Psych::SyntaxError => e
+          return ["YAML syntax error: #{e.message}"]
+        end
+
+        unless parsed.is_a?(Hash)
+          return ["Invalid manifest: expected a YAML mapping"]
+        end
+
+        unless parsed["apiVersion"]
+          errors << "Missing required field 'apiVersion'"
+        end
+
+        if parsed["apiVersion"] && parsed["apiVersion"] != API_VERSION
+          errors << "Unsupported apiVersion '#{parsed["apiVersion"]}'. Expected: #{API_VERSION}"
+        end
+
+        errors << "Missing required field 'kind'" unless parsed["kind"]
+
+        if parsed["kind"] && !KINDS_REVERSE.key?(parsed["kind"])
+          errors << "Unknown kind '#{parsed["kind"]}'. Valid: #{KINDS.values.join(', ')}"
+        end
+
+        metadata = parsed["metadata"]
+        if metadata.nil? || !metadata.is_a?(Hash)
+          errors << "Missing required field 'metadata'"
+        end
+
+        errors
+      end
+
+      private
+
+      # Builds string-keyed metadata hash from symbol-keyed input.
+      #
+      # @param metadata [Hash] symbol-keyed metadata
+      # @return [Hash] string-keyed metadata for YAML output
+      def build_metadata(metadata)
+        result = {}
+        result["vmid"] = metadata[:vmid] if metadata[:vmid]
+        result["name"] = metadata[:name] if metadata[:name]
+        result["node"] = metadata[:node] if metadata[:node]
+        result["status"] = metadata[:status] if metadata[:status]
+        result["tags"] = metadata[:tags] if metadata[:tags]
+        result
+      end
+
+      # Recursively converts symbol keys to string keys.
+      #
+      # @param hash [Hash] symbol-keyed hash
+      # @return [Hash] string-keyed hash
+      def stringify_keys_deep(hash)
+        hash.transform_keys(&:to_s).transform_values do |v|
+          v.is_a?(Hash) ? stringify_keys_deep(v) : v
+        end
+      end
+
+      # Converts string-keyed metadata to symbol-keyed hash.
+      #
+      # @param hash [Hash] string-keyed metadata from YAML
+      # @return [Hash] symbol-keyed metadata
+      def symbolize_metadata(hash)
+        result = {}
+        result[:vmid] = hash["vmid"] if hash["vmid"]
+        result[:name] = hash["name"] if hash["name"]
+        result[:node] = hash["node"] if hash["node"]
+        result[:status] = hash["status"] if hash["status"]
+        result[:tags] = hash["tags"] if hash["tags"]
+        result
+      end
+
+      # Recursively converts string keys to symbol keys.
+      #
+      # @param hash [Hash] string-keyed hash from YAML
+      # @return [Hash] symbol-keyed hash
+      def symbolize_keys_deep(hash)
+        hash.to_h do |k, v|
+          [k.to_sym, v.is_a?(Hash) ? symbolize_keys_deep(v) : v]
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/models/apt_package.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Models
+    # Represents an APT package on a Proxmox node.
+    #
+    # Single model serves both pending updates (`/apt/update`) and installed
+    # package versions (`/apt/versions`). Some attributes only apply to one
+    # API: `notify_status` to pending updates, `current_state`,
+    # `manager_version`, `running_kernel` to versions.
+    #
+    # @example Creating a pending update instance
+    #   pkg = AptPackage.new(
+    #     Package: "pve-manager",
+    #     Version: "8.2.4-1",
+    #     OldVersion: "8.2.3-1",
+    #     Origin: "Proxmox",
+    #     node: "pve1"
+    #   )
+    #   pkg.package # => "pve-manager"
+    #   pkg.upgrade? # => true
+    #
+    # @see Pvectl::Repositories::Apt Repository that creates these instances
+    #
+    class AptPackage < Base
+      # @return [String, nil] package name
+      attr_reader :package
+
+      # @return [String, nil] short package title
+      attr_reader :title
+
+      # @return [String, nil] available / target version
+      attr_reader :version
+
+      # @return [String, nil] currently installed version
+      attr_reader :old_version
+
+      # @return [String, nil] package origin (e.g., "Proxmox", "Debian")
+      attr_reader :origin
+
+      # @return [String, nil] package section
+      attr_reader :section
+
+      # @return [String, nil] package priority
+      attr_reader :priority
+
+      # @return [String, nil] architecture (amd64, arm64, all, ...)
+      attr_reader :arch
+
+      # @return [String, nil] package description
+      attr_reader :description
+
+      # @return [String, nil] notify status (pending updates only)
+      attr_reader :notify_status
+
+      # @return [String, nil] current installed state (versions only)
+      attr_reader :current_state
+
+      # @return [String, nil] pve-manager API server version (versions only)
+      attr_reader :manager_version
+
+      # @return [String, nil] running kernel (proxmox-ve package, versions only)
+      attr_reader :running_kernel
+
+      # @return [String, nil] node name this package belongs to
+      attr_reader :node
+
+      # Creates a new AptPackage instance.
+      #
+      # Accepts Proxmox API capitalized keys (`Package`, `OldVersion`, ...) as
+      # well as snake_case / dasherized variants. Indifferent access on keys.
+      #
+      # @param attrs [Hash] package attributes from API
+      def initialize(attrs = {})
+        super
+        @package = attributes[:Package] || attributes[:package]
+        @title = attributes[:Title] || attributes[:title]
+        @version = attributes[:Version] || attributes[:version]
+        @old_version = attributes[:OldVersion] || attributes[:old_version] || attributes[:"old-version"]
+        @origin = attributes[:Origin] || attributes[:origin]
+        @section = attributes[:Section] || attributes[:section]
+        @priority = attributes[:Priority] || attributes[:priority]
+        @arch = attributes[:Arch] || attributes[:arch]
+        @description = attributes[:Description] || attributes[:description]
+        @notify_status = attributes[:NotifyStatus] || attributes[:notify_status] || attributes[:"notify-status"]
+        @current_state = attributes[:CurrentState] || attributes[:current_state] || attributes[:"current-state"]
+        @manager_version = attributes[:ManagerVersion] || attributes[:manager_version] || attributes[:"manager-version"]
+        @running_kernel = attributes[:RunningKernel] || attributes[:running_kernel] || attributes[:"running-kernel"]
+        @node = attributes[:node]
+      end
+
+      # Returns true if a different version is available.
+      #
+      # @return [Boolean] true if old_version and version are both set and differ
+      def upgrade?
+        !old_version.nil? && !version.nil? && old_version != version
+      end
+
+      # Returns the installed package state, defaults to "Installed" when not provided.
+      #
+      # @return [String] installed state
+      def installed_state
+        current_state || "Installed"
+      end
+    end
+  end
+end

data/lib/pvectl/models/backup.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Models
+    # Represents a VM/container backup in Proxmox.
+    #
+    # A backup is a full copy of a VM or container stored on a storage backend.
+    # Backups can be created via vzdump and restored to create new VMs/containers.
+    #
+    # @example Creating a backup model
+    #   backup = Backup.new(
+    #     volid: "local:backup/vzdump-qemu-100-2024_01_15-10_30_00.vma.zst",
+    #     vmid: 100,
+    #     size: 1610612736,
+    #     ctime: 1705315800,
+    #     format: "vma"
+    #   )
+    #   backup.human_size   # => "1.5 GiB"
+    #   backup.vm?          # => true
+    #
+    # @see Pvectl::Models::Base Base model class
+    #
+    class Backup < Base
+      # @return [String] full volume identifier (e.g., "local:backup/vzdump-qemu-100-xxx.vma.zst")
+      attr_reader :volid
+
+      # @return [Integer] VM/container ID
+      attr_reader :vmid
+
+      # @return [String, nil] node name where backup is stored
+      attr_reader :node
+
+      # @return [String, nil] storage name (extracted from volid)
+      attr_reader :storage
+
+      # @return [Symbol, nil] resource type (:qemu or :lxc)
+      attr_reader :resource_type
+
+      # @return [String, nil] backup format ("vma", "tar")
+      attr_reader :format
+
+      # @return [Integer, nil] backup size in bytes
+      attr_reader :size
+
+      # @return [Integer, nil] Unix timestamp when backup was created
+      attr_reader :ctime
+
+      # @return [String, nil] optional notes/description
+      attr_reader :notes
+
+      # @return [Boolean] whether backup is protected from deletion
+      attr_reader :protected
+
+      # Creates a new Backup instance.
+      #
+      # @param attrs [Hash] backup attributes
+      # @option attrs [String] :volid volume identifier
+      # @option attrs [Integer] :vmid VM/container ID
+      # @option attrs [String] :node node name
+      # @option attrs [String] :storage storage name (auto-detected from volid if not provided)
+      # @option attrs [Symbol] :resource_type :qemu or :lxc (auto-detected from volid if not provided)
+      # @option attrs [String] :format backup format
+      # @option attrs [Integer] :size size in bytes
+      # @option attrs [Integer] :ctime Unix timestamp of creation
+      # @option attrs [String] :notes description
+      # @option attrs [Boolean] :protected protection status
+      def initialize(attrs = {})
+        super
+        @volid = attributes[:volid]
+        @vmid = attributes[:vmid]
+        @node = attributes[:node]
+        @storage = attributes[:storage] || extract_storage
+        @resource_type = attributes[:resource_type] || detect_resource_type
+        @format = attributes[:format]
+        @size = attributes[:size]
+        @ctime = attributes[:ctime]
+        @notes = attributes[:notes]
+        @protected = attributes[:protected] || false
+      end
+
+      # Returns the backup creation time as a Time object.
+      #
+      # @return [Time, nil] creation time or nil if ctime is not set
+      def created_at
+        return nil if ctime.nil?
+
+        Time.at(ctime)
+      end
+
+      # Checks if the backup is for a VM (QEMU).
+      #
+      # @return [Boolean] true if resource_type is :qemu
+      def vm?
+        resource_type == :qemu
+      end
+
+      # Checks if the backup is for a container (LXC).
+      #
+      # @return [Boolean] true if resource_type is :lxc
+      def container?
+        resource_type == :lxc
+      end
+
+      # Extracts the filename from the volume identifier.
+      #
+      # @return [String, nil] filename or nil if volid is not set
+      def filename
+        return nil if volid.nil?
+
+        volid.split("/").last
+      end
+
+      # Returns human-readable size.
+      #
+      # @return [String, nil] formatted size (e.g., "1.5 GiB") or nil if size is not set
+      def human_size
+        return nil if size.nil?
+
+        format_bytes(size)
+      end
+
+      # Checks if the backup is protected from deletion.
+      #
+      # @return [Boolean] true if protected
+      def protected?
+        @protected == true
+      end
+
+      private
+
+      # Extracts storage name from volid.
+      #
+      # @return [String, nil] storage name
+      def extract_storage
+        return nil if volid.nil?
+
+        volid.split(":").first
+      end
+
+      # Detects resource type from volid pattern.
+      #
+      # @return [Symbol, nil] :qemu, :lxc, or nil
+      def detect_resource_type
+        return nil if volid.nil?
+        return :qemu if volid.include?("vzdump-qemu")
+        return :lxc if volid.include?("vzdump-lxc")
+
+        nil
+      end
+
+      # Formats bytes into human-readable units.
+      #
+      # @param bytes [Integer] size in bytes
+      # @return [String] formatted size
+      def format_bytes(bytes)
+        units = ["B", "KiB", "MiB", "GiB", "TiB"]
+        unit_index = 0
+        value = bytes.to_f
+
+        while value >= 1024 && unit_index < units.size - 1
+          value /= 1024
+          unit_index += 1
+        end
+
+        if unit_index == 0
+          "#{value.to_i} #{units[unit_index]}"
+        else
+          "#{Kernel.format('%.1f', value)} #{units[unit_index]}"
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/models/base.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Models
+    # Abstract base class for domain models.
+    #
+    # Provides common initialization from hash attributes.
+    # All models are immutable - only getters, no setters.
+    #
+    # Subclasses store domain data and contain domain logic,
+    # but do not fetch data themselves (that's the Repository's job).
+    #
+    # @abstract Subclass and add attr_readers for domain attributes.
+    #
+    # @example Implementing a model
+    #   class Vm < Base
+    #     attr_reader :vmid, :name, :status
+    #
+    #     def initialize(attributes = {})
+    #       super
+    #       @vmid = attributes[:vmid]
+    #       @name = attributes[:name]
+    #       @status = attributes[:status]
+    #     end
+    #
+    #     def running?
+    #       status == "running"
+    #     end
+    #   end
+    #
+    # @see Pvectl::Repositories::Base Repository creates model instances
+    #
+    class Base
+      # Creates model from attributes hash.
+      #
+      # Converts string keys to symbols for consistent access.
+      #
+      # @param attributes [Hash] attribute key-value pairs
+      def initialize(attributes = {})
+        @attributes = (attributes || {}).transform_keys(&:to_sym)
+      end
+
+      protected
+
+      # @return [Hash] the raw attributes hash
+      attr_reader :attributes
+    end
+  end
+end

data/lib/pvectl/models/capability.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Models
+    # Represents a single node capability entry — either a supported QEMU
+    # CPU model or a supported QEMU machine type.
+    #
+    # The two kinds share a flat structure with different optional fields
+    # populated. A small, kind-aware model keeps the presenter simple while
+    # still allowing JSON/YAML output to expose all relevant attributes.
+    #
+    # @example QEMU CPU capability
+    #   cap = Capability.new(node_name: "pve1", kind: :cpu, name: "host", vendor: "Intel")
+    #
+    # @example QEMU machine type capability
+    #   cap = Capability.new(node_name: "pve1", kind: :machine, name: "pc-q35-8.1", machine_type: "q35", version: "8.1")
+    #
+    # @see Pvectl::Repositories::Capabilities Repository producing instances
+    # @see Pvectl::Presenters::Capability Presenter for display
+    #
+    class Capability < Base
+      # @return [String, nil] node the capability belongs to
+      attr_reader :node_name
+
+      # @return [Symbol] capability kind: :cpu or :machine
+      attr_reader :kind
+
+      # @return [String, nil] identifying name (CPU model or machine id)
+      attr_reader :name
+
+      # @return [String, nil] CPU vendor (only for :cpu kind)
+      attr_reader :vendor
+
+      # @return [Boolean] true when this is a custom CPU model (only :cpu)
+      attr_reader :custom
+
+      # @return [String, nil] machine type — q35 or i440fx (only :machine)
+      attr_reader :machine_type
+
+      # @return [String, nil] machine version (only :machine)
+      attr_reader :version
+
+      # @return [String, nil] notable changes for the version (only :machine)
+      attr_reader :changes
+
+      # Creates a new Capability.
+      #
+      # @param attributes [Hash] attribute hash
+      def initialize(attributes = {})
+        super
+        @node_name = @attributes[:node_name]
+        @kind = @attributes[:kind]
+        @name = @attributes[:name]
+        @vendor = @attributes[:vendor]
+        @custom = @attributes[:custom] || false
+        @machine_type = @attributes[:machine_type]
+        @version = @attributes[:version]
+        @changes = @attributes[:changes]
+      end
+    end
+  end
+end