pvectl 0.2.0

data/lib/pvectl/models/operation_result.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Models
+    # Represents the result of a lifecycle operation on a VM.
+    #
+    # Combines VM, task status, and error information into a single object
+    # for consistent presentation of operation results.
+    #
+    # @example Successful sync operation
+    #   result = OperationResult.new(vm: vm, task: task, success: task.successful?)
+    #   result.successful? #=> true
+    #   result.message #=> "OK"
+    #
+    # @example Async operation (pending)
+    #   result = OperationResult.new(vm: vm, task_upid: upid, success: :pending)
+    #   result.pending? #=> true
+    #   result.message #=> "Task: UPID:pve1:..."
+    #
+    # @example Failed operation
+    #   result = OperationResult.new(vm: vm, success: false, error: "Permission denied")
+    #   result.failed? #=> true
+    #   result.message #=> "Permission denied"
+    #
+    class OperationResult < Base
+      # @return [Hash, nil] Generic resource info (for snapshot/backup operations)
+      attr_reader :resource
+
+      # @return [Symbol] The operation performed (:start, :stop, etc.)
+      attr_reader :operation
+
+      # @return [Models::Task, nil] The task (for completed sync operations)
+      attr_reader :task
+
+      # @return [String, nil] The task UPID (for async operations)
+      attr_reader :task_upid
+
+      # @return [Boolean, Symbol] true, false, or :pending
+      attr_reader :success
+
+      # @return [String, nil] Error message if operation failed
+      attr_reader :error
+
+      # Creates a new OperationResult.
+      #
+      # @param attrs [Hash] Result attributes
+      def initialize(attrs = {})
+        super(attrs)
+        @resource = @attributes[:resource]
+        @operation = @attributes[:operation]
+        @task = @attributes[:task]
+        @task_upid = @attributes[:task_upid]
+        @success = @attributes[:success]
+        @error = @attributes[:error]
+      end
+
+      # Checks if the operation was successful.
+      #
+      # @return [Boolean] true if success is true or task succeeded
+      def successful?
+        success == true || task&.successful?
+      end
+
+      # Checks if the operation failed.
+      #
+      # @return [Boolean] true if success is false, :partial, or task failed
+      def failed?
+        success == false || success == :partial || task&.failed?
+      end
+
+      # Checks if the operation is still pending (async).
+      #
+      # @return [Boolean] true if success is :pending or task is pending
+      def pending?
+        success == :pending || task&.pending?
+      end
+
+      # Checks if the operation partially succeeded (e.g. clone OK, config update failed).
+      #
+      # @return [Boolean] true if success is :partial
+      def partial?
+        success == :partial
+      end
+
+      # Returns human-readable status.
+      #
+      # @return [String] "Pending", "Success", or "Failed"
+      def status_text
+        return "Pending" if pending?
+        return "Partial" if partial?
+        return "Success" if successful?
+
+        "Failed"
+      end
+
+      # Returns the result message for display.
+      #
+      # Priority: error > task.exitstatus > task_upid > status_text
+      #
+      # @return [String] Result message
+      def message
+        return error if error
+        return task.exitstatus if task
+        return "Task: #{task_upid}" if task_upid
+
+        status_text
+      end
+    end
+  end
+end

data/lib/pvectl/models/physical_disk.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Models
+    # Represents a physical disk (block device) on a Proxmox node.
+    #
+    # PhysicalDisk instances are created from the Proxmox API responses
+    # and provide domain methods for disk analysis.
+    #
+    # @example Creating a disk from API data
+    #   disk = PhysicalDisk.new(
+    #     devpath: "/dev/sda",
+    #     model: "Samsung SSD 970",
+    #     size: 500_000_000_000,
+    #     type: "ssd",
+    #     health: "PASSED",
+    #     node: "pve1",
+    #     gpt: 1,
+    #     mounted: 1,
+    #     used: "LVM"
+    #   )
+    #   disk.ssd?      # => true
+    #   disk.healthy?  # => true
+    #   disk.size_gb   # => 465.7
+    #   disk.gpt?      # => true
+    #   disk.mounted?  # => true
+    #   disk.osd?      # => false
+    #
+    # @see Pvectl::Models::Base Base class for all models
+    #
+    class PhysicalDisk < Base
+      # @return [String, nil] device path (e.g., "/dev/sda")
+      attr_reader :devpath
+
+      # @return [String, nil] disk model name
+      attr_reader :model
+
+      # @return [Integer, nil] disk size in bytes
+      attr_reader :size
+
+      # @return [String, nil] disk type ("ssd", "hdd", etc.)
+      attr_reader :type
+
+      # @return [String, nil] SMART health status (e.g., "PASSED", "FAILED")
+      attr_reader :health
+
+      # @return [String, nil] disk serial number
+      attr_reader :serial
+
+      # @return [String, nil] disk vendor
+      attr_reader :vendor
+
+      # @return [String, nil] Proxmox node name this disk belongs to
+      attr_reader :node
+
+      # @return [Integer, nil] whether disk has a GPT partition table (1 = yes, 0 = no)
+      attr_reader :gpt
+
+      # @return [Integer, nil] whether disk is mounted (1 = yes, 0 = no)
+      attr_reader :mounted
+
+      # @return [String, nil] how the disk is used (e.g., "LVM", "ZFS", "ext4")
+      attr_reader :used
+
+      # @return [String, nil] World Wide Name identifier
+      attr_reader :wwn
+
+      # @return [Integer, nil] Ceph OSD ID (-1 if not an OSD)
+      attr_reader :osdid
+
+      # @return [String, nil] parent device path (e.g., "/dev/sda" for partition "/dev/sda1")
+      attr_reader :parent
+
+      # @return [String, nil] SMART type ("ata" or "text")
+      attr_reader :smart_type
+
+      # @return [Array<Hash>, nil] ATA SMART attributes array
+      attr_reader :smart_attributes
+
+      # @return [String, nil] raw SMART text (NVMe/SAS)
+      attr_reader :smart_text
+
+      # @return [Integer, nil] disk wearout percentage
+      attr_reader :wearout
+
+      # Creates a new PhysicalDisk instance.
+      #
+      # @param attrs [Hash] disk attributes from API
+      # @option attrs [String] :devpath device path
+      # @option attrs [String] :model disk model name
+      # @option attrs [Integer] :size disk size in bytes
+      # @option attrs [String] :type disk type
+      # @option attrs [String] :health SMART health status
+      # @option attrs [String] :serial serial number
+      # @option attrs [String] :vendor vendor name
+      # @option attrs [String] :node Proxmox node name
+      # @option attrs [Integer] :gpt GPT partition table flag (1/0)
+      # @option attrs [Integer] :mounted mounted flag (1/0)
+      # @option attrs [String] :used usage type
+      # @option attrs [String] :wwn World Wide Name
+      # @option attrs [Integer] :osdid Ceph OSD ID
+      # @option attrs [String] :parent parent device path
+      # @option attrs [String] :smart_type SMART data type ("ata" or "text")
+      # @option attrs [Array<Hash>] :smart_attributes ATA SMART attributes
+      # @option attrs [String] :smart_text raw SMART text (NVMe/SAS)
+      # @option attrs [Integer] :wearout wearout percentage
+      def initialize(attrs = {})
+        super
+        @devpath = attributes[:devpath]
+        @model = attributes[:model]
+        @size = attributes[:size]
+        @type = attributes[:type]
+        @health = attributes[:health]
+        @serial = attributes[:serial]
+        @vendor = attributes[:vendor]
+        @node = attributes[:node]
+        @gpt = attributes[:gpt]
+        @mounted = attributes[:mounted]
+        @used = attributes[:used]
+        @wwn = attributes[:wwn]
+        @osdid = attributes[:osdid]
+        @parent = attributes[:parent]
+        @smart_type = attributes[:smart_type]
+        @smart_attributes = attributes[:smart_attributes]
+        @smart_text = attributes[:smart_text]
+        @wearout = attributes[:wearout]
+      end
+
+      # Returns disk size in gigabytes.
+      #
+      # @return [Float, nil] size in GB (binary, 1024-based), or nil if size unknown
+      #
+      # @example
+      #   disk = PhysicalDisk.new(size: 500_000_000_000)
+      #   disk.size_gb # => 465.7
+      def size_gb
+        return nil if size.nil?
+
+        (size.to_f / 1024 / 1024 / 1024).round(1)
+      end
+
+      # Checks if disk SMART health status is PASSED.
+      #
+      # @return [Boolean] true if health is "PASSED"
+      def healthy?
+        health == "PASSED"
+      end
+
+      # Checks if disk is an SSD.
+      #
+      # @return [Boolean] true if type is "ssd"
+      def ssd?
+        type == "ssd"
+      end
+
+      # Checks if disk has a GPT partition table.
+      #
+      # @return [Boolean] true if gpt is 1
+      def gpt?
+        gpt == 1
+      end
+
+      # Checks if disk is currently mounted.
+      #
+      # @return [Boolean] true if mounted is 1
+      def mounted?
+        mounted == 1
+      end
+
+      # Checks if disk is a Ceph OSD.
+      #
+      # @return [Boolean] true if osdid is non-nil and >= 0
+      def osd?
+        !osdid.nil? && osdid >= 0
+      end
+
+      # Merges SMART data into the model.
+      #
+      # Called after initial construction when SMART data is fetched separately
+      # from the disk list endpoint.
+      #
+      # @param smart_data [Hash{Symbol => untyped}] SMART response data
+      # @return [void]
+      def merge_smart(smart_data)
+        @smart_type = smart_data[:type]
+        @smart_attributes = smart_data[:attributes]
+        @smart_text = smart_data[:text]
+        @wearout = smart_data[:wearout]
+        @health = smart_data[:health] if smart_data[:health]
+      end
+    end
+  end
+end

data/lib/pvectl/models/service.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Models
+    # Represents a Proxmox service running on a node.
+    #
+    # Services are system daemons that make up the Proxmox VE platform,
+    # such as pveproxy, pvedaemon, pve-cluster, etc.
+    #
+    # @example Creating a service instance
+    #   service = Service.new(
+    #     service: "pveproxy",
+    #     name: "pveproxy",
+    #     state: "running",
+    #     desc: "PVE API Proxy Server"
+    #   )
+    #   service.running? # => true
+    #
+    # @see Pvectl::Repositories::Service Repository that creates these instances
+    #
+    class Service < Base
+      # @return [String] the service identifier
+      attr_reader :service
+
+      # @return [String, nil] the display name of the service
+      attr_reader :name
+
+      # @return [String] the current state (running, stopped, etc.)
+      attr_reader :state
+
+      # @return [String, nil] the service description
+      attr_reader :desc
+
+      # @return [String, nil] systemd ActiveState (active, inactive, failed, ...)
+      attr_reader :active_state
+
+      # @return [String, nil] systemd UnitFileState (enabled, disabled, masked, ...)
+      attr_reader :unit_state
+
+      # @return [String, nil] node name this service belongs to
+      attr_reader :node
+
+      # Creates a new Service instance.
+      #
+      # @param attrs [Hash] service attributes
+      # @option attrs [String] :service the service identifier
+      # @option attrs [String] :name the display name
+      # @option attrs [String] :state the current state
+      # @option attrs [String] :desc the description
+      # @option attrs [String] :active_state systemd ActiveState
+      # @option attrs [String] :unit_state systemd UnitFileState
+      # @option attrs [String] :node the node this service runs on
+      def initialize(attrs = {})
+        super
+        @service = attributes[:service]
+        @name = attributes[:name]
+        @state = attributes[:state]
+        @desc = attributes[:desc]
+        # Accept both symbol keys (:active_state) and dasherized keys (:"active-state")
+        @active_state = attributes[:active_state] || attributes[:"active-state"]
+        @unit_state = attributes[:unit_state] || attributes[:"unit-state"]
+        @node = attributes[:node]
+      end
+
+      # Checks if the service is currently running.
+      #
+      # @return [Boolean] true if state is "running"
+      def running?
+        state == "running"
+      end
+
+      # Returns the display name, falling back to service identifier.
+      #
+      # @return [String] the name to display
+      def display_name
+        name || service
+      end
+    end
+  end
+end

data/lib/pvectl/models/snapshot.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Models
+    # Represents a VM/container snapshot in Proxmox.
+    #
+    # A snapshot captures the state of a VM or container at a specific point in time,
+    # including optionally the VM memory state (vmstate).
+    #
+    # @example Creating a snapshot model
+    #   snapshot = Snapshot.new(
+    #     name: "before-upgrade",
+    #     snaptime: 1706800000,
+    #     description: "Snapshot before upgrade",
+    #     vmstate: 1
+    #   )
+    #   snapshot.has_vmstate?  # => true
+    #   snapshot.created_at    # => 2024-02-01 12:26:40 +0000
+    #
+    # @see Pvectl::Models::Base Base model class
+    #
+    class Snapshot < Base
+      # @return [String] snapshot name/identifier
+      attr_reader :name
+
+      # @return [Integer, nil] Unix timestamp when snapshot was created
+      attr_reader :snaptime
+
+      # @return [String, nil] optional description of the snapshot
+      attr_reader :description
+
+      # @return [Integer, nil] 1 if VM memory state was saved, 0 or nil otherwise
+      attr_reader :vmstate
+
+      # @return [String, nil] parent snapshot name for snapshot trees
+      attr_reader :parent
+
+      # @return [Integer, nil] VM/container ID this snapshot belongs to
+      attr_reader :vmid
+
+      # @return [String, nil] node name where the VM/container resides
+      attr_reader :node
+
+      # @return [Symbol, nil] resource type (:qemu for VM, :lxc for container)
+      attr_reader :resource_type
+
+      # Creates a new Snapshot instance.
+      #
+      # @param attrs [Hash] snapshot attributes
+      # @option attrs [String] :name snapshot name
+      # @option attrs [Integer] :snaptime Unix timestamp of creation
+      # @option attrs [String] :description snapshot description
+      # @option attrs [Integer] :vmstate 1 if VM state saved, 0 otherwise
+      # @option attrs [String] :parent parent snapshot name
+      # @option attrs [Integer] :vmid VM/container ID
+      # @option attrs [String] :node node name
+      # @option attrs [Symbol] :resource_type :qemu or :lxc
+      def initialize(attrs = {})
+        super
+        @name = attributes[:name]
+        @snaptime = attributes[:snaptime]
+        @description = attributes[:description]
+        @vmstate = attributes[:vmstate]
+        @parent = attributes[:parent]
+        @vmid = attributes[:vmid]
+        @node = attributes[:node]
+        @resource_type = attributes[:resource_type]
+      end
+
+      # Checks if the snapshot includes VM memory state.
+      #
+      # @return [Boolean] true if vmstate equals 1
+      def has_vmstate?
+        vmstate == 1
+      end
+
+      # Returns the snapshot creation time as a Time object.
+      #
+      # @return [Time, nil] creation time or nil if snaptime is not set
+      def created_at
+        return nil if snaptime.nil?
+
+        Time.at(snaptime)
+      end
+
+      # Checks if the snapshot belongs to a VM (QEMU).
+      #
+      # @return [Boolean] true if resource_type is :qemu
+      def vm?
+        resource_type == :qemu
+      end
+
+      # Checks if the snapshot belongs to a container (LXC).
+      #
+      # @return [Boolean] true if resource_type is :lxc
+      def container?
+        resource_type == :lxc
+      end
+    end
+  end
+end

data/lib/pvectl/models/snapshot_description.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Models
+    # Wraps snapshot describe data: target snapshot + siblings for tree building.
+    #
+    # Used by the describe command to return rich snapshot data without
+    # changing the existing single-model return convention in ResourceService.
+    #
+    # @example Single VM
+    #   desc = SnapshotDescription.new(entries: [
+    #     SnapshotDescription::Entry.new(snapshot: snap, siblings: all_snaps)
+    #   ])
+    #
+    # @example Multiple VMs
+    #   desc = SnapshotDescription.new(entries: [entry1, entry2])
+    #   desc.single? # => false
+    #
+    class SnapshotDescription
+      # Holds a single snapshot + its siblings for one VM/container.
+      Entry = Struct.new(:snapshot, :siblings, keyword_init: true)
+
+      # @return [Array<Entry>] entries per VM/container
+      attr_reader :entries
+
+      # @param entries [Array<Entry>] snapshot entries
+      def initialize(entries:)
+        @entries = entries
+      end
+
+      # Returns true when describing a snapshot from a single VM.
+      #
+      # @return [Boolean]
+      def single?
+        entries.length == 1
+      end
+    end
+  end
+end

data/lib/pvectl/models/storage.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Models
+    # Represents a storage pool in the Proxmox cluster.
+    #
+    # Immutable domain model containing storage attributes and predicate methods.
+    # Created by Repositories::Storage from API data.
+    # Display formatting is handled by Presenters::Storage.
+    #
+    # @example Creating a Storage model
+    #   storage = Storage.new(name: "local", plugintype: "dir", status: "available")
+    #   storage.active? #=> true
+    #   storage.shared? #=> false
+    #
+    # @example From API response
+    #   data = { "storage" => "local", "plugintype" => "dir", "status" => "available" }
+    #   storage = Storage.new(data)
+    #
+    # @see Pvectl::Repositories::Storage Repository that creates Storage instances
+    # @see Pvectl::Presenters::Storage Presenter for formatting Storage data
+    #
+    class Storage < Base
+      # @return [String] storage pool name
+      attr_reader :name
+
+      # @return [String] storage plugin type (dir, lvmthin, rbd, nfs, zfspool, etc.)
+      attr_reader :plugintype
+
+      # @return [String] storage status (available, unavailable)
+      attr_reader :status
+
+      # @return [String, nil] node name (nil for shared storage)
+      attr_reader :node
+
+      # @return [Integer, nil] disk used in bytes
+      attr_reader :disk
+
+      # @return [Integer, nil] total disk in bytes
+      attr_reader :maxdisk
+
+      # @return [String, nil] comma-separated content types (images, iso, vztmpl, backup, rootdir)
+      attr_reader :content
+
+      # @return [Integer] shared flag (1 = shared, 0 = local)
+      attr_reader :shared
+
+      # @return [Integer, nil] available bytes (from /nodes/{node}/storage)
+      attr_reader :avail
+
+      # @return [Integer, nil] enabled flag (0/1) (from /nodes/{node}/storage)
+      attr_reader :enabled
+
+      # @return [Integer, nil] active flag (0/1) (from /nodes/{node}/storage)
+      attr_reader :active_flag
+
+      # Configuration fields (from /storage/{storage} API endpoint)
+      # @return [String, nil] path for dir, nfs storage types
+      attr_reader :path
+
+      # @return [String, nil] server for nfs, iscsi, ceph
+      attr_reader :server
+
+      # @return [String, nil] export path (nfs)
+      attr_reader :export
+
+      # @return [String, nil] pool name (zfs, ceph)
+      attr_reader :pool
+
+      # @return [String, nil] volume group (lvm)
+      attr_reader :vgname
+
+      # @return [String, nil] thin pool name (lvmthin)
+      attr_reader :thinpool
+
+      # @return [String, nil] allowed nodes (nil = all)
+      attr_reader :nodes_allowed
+
+      # @return [Hash, nil] retention policy hash
+      attr_reader :prune_backups
+
+      # @return [Integer, nil] max backups (deprecated)
+      attr_reader :max_files
+
+      # Content summary
+      # @return [Array<Hash>] volumes from /content endpoint
+      attr_reader :volumes
+
+      # Creates a new Storage model from attributes.
+      #
+      # Handles field aliasing between different API endpoints:
+      # - /cluster/resources uses: disk, maxdisk
+      # - /nodes/{node}/storage uses: used, total, avail
+      #
+      # @param attrs [Hash] Storage attributes from API (string or symbol keys)
+      def initialize(attrs = {})
+        super(attrs)
+        @name = @attributes[:name] || @attributes[:storage]
+        @plugintype = @attributes[:plugintype] || @attributes[:type]
+        @node = @attributes[:node]
+        @content = @attributes[:content]
+        @shared = @attributes[:shared] || 0
+
+        # Handle field aliasing between endpoints
+        # /cluster/resources uses: disk, maxdisk
+        # /nodes/{node}/storage uses: used, total, avail
+        @disk = @attributes[:disk] || @attributes[:used]
+        @maxdisk = @attributes[:maxdisk] || @attributes[:total]
+        @avail = @attributes[:avail]
+        @enabled = @attributes[:enabled]
+        @active_flag = @attributes[:active]
+
+        # Status normalization: /nodes/{node}/storage has no status field
+        # Derive from active flag if status not present
+        @status = @attributes[:status] || derive_status_from_active
+
+        # Configuration fields from /storage/{storage} API endpoint
+        @path = @attributes[:path]
+        @server = @attributes[:server]
+        @export = @attributes[:export]
+        @pool = @attributes[:pool]
+        @vgname = @attributes[:vgname]
+        @thinpool = @attributes[:thinpool]
+        @nodes_allowed = @attributes[:nodes]  # API returns "nodes" not "nodes_allowed"
+        @prune_backups = @attributes[:"prune-backups"]  # API uses hyphen
+        @max_files = @attributes[:maxfiles]
+        @volumes = @attributes[:volumes] || []
+      end
+
+      # Checks if the storage is active/available.
+      #
+      # @return [Boolean] true if status is "available" or "active"
+      def active?
+        status == "available" || status == "active"
+      end
+
+      # Returns used bytes (alias for disk).
+      # Provides semantic clarity when working with /nodes/{node}/storage API.
+      #
+      # @return [Integer, nil] bytes used
+      def used
+        disk
+      end
+
+      # Returns total bytes (alias for maxdisk).
+      # Provides semantic clarity when working with /nodes/{node}/storage API.
+      #
+      # @return [Integer, nil] total bytes
+      def total
+        maxdisk
+      end
+
+      # Checks if the storage is enabled.
+      #
+      # @return [Boolean] true if enabled flag is 1
+      def enabled?
+        enabled == 1
+      end
+
+      # Checks if the storage is shared across nodes.
+      #
+      # @return [Boolean] true if shared flag is 1
+      def shared?
+        shared == 1
+      end
+
+      private
+
+      # Derives status from active flag when status not present.
+      # Used for /nodes/{node}/storage API which doesn't return status field.
+      #
+      # @return [String, nil] derived status or nil if active_flag not set
+      def derive_status_from_active
+        return nil if @active_flag.nil?
+
+        @active_flag == 1 ? "available" : "unavailable"
+      end
+    end
+  end
+end