pvectl 0.2.0

data/lib/pvectl/repositories/service.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Repositories
+    # Repository for systemd services on Proxmox nodes.
+    #
+    # Wraps the `/nodes/{node}/services` API endpoints. Provides listing of
+    # services on a node and lifecycle operations (start/stop/restart/reload)
+    # which return Proxmox task UPIDs.
+    #
+    # @example Listing services on a node
+    #   repo = Service.new(connection)
+    #   services = repo.list(node: "pve1")
+    #   services.each { |s| puts "#{s.service}: #{s.active_state}" }
+    #
+    # @example Restarting a service
+    #   upid = repo.restart("pve1", "pveproxy")
+    #
+    # @see Pvectl::Models::Service Service model
+    # @see Pvectl::Connection API connection
+    #
+    class Service < Base
+      # Lists systemd services on a node.
+      #
+      # When node is nil, iterates over all online nodes in the cluster.
+      # When node is specified, queries only that node.
+      #
+      # @param node [String, nil] node name (or nil for all online nodes)
+      # @return [Array<Models::Service>] collection of Service models
+      def list(node: nil)
+        if node
+          services_for_node(node)
+        else
+          online_nodes.flat_map { |node_name| services_for_node(node_name) }
+        end
+      end
+
+      # Reads single service state.
+      #
+      # @param node [String] node name
+      # @param service [String] service identifier (e.g., "pveproxy")
+      # @return [Models::Service, nil] service model or nil on error
+      def state(node, service)
+        resp = connection.client["nodes/#{node}/services/#{service}/state"].get
+        data = extract_data(resp)
+        return nil if data.nil? || data.empty?
+
+        build_model(data.merge(node: node))
+      rescue StandardError
+        nil
+      end
+
+      # Starts a service. Returns the task UPID.
+      #
+      # @param node [String] node name
+      # @param service [String] service identifier
+      # @return [String] task UPID
+      def start(node, service)
+        post_action(node, service, "start")
+      end
+
+      # Stops a service. Returns the task UPID.
+      #
+      # @param node [String] node name
+      # @param service [String] service identifier
+      # @return [String] task UPID
+      def stop(node, service)
+        post_action(node, service, "stop")
+      end
+
+      # Hard-restarts a service. Returns the task UPID.
+      #
+      # @param node [String] node name
+      # @param service [String] service identifier
+      # @return [String] task UPID
+      def restart(node, service)
+        post_action(node, service, "restart")
+      end
+
+      # Reloads a service (falls back to restart if unsupported). Returns the task UPID.
+      #
+      # @param node [String] node name
+      # @param service [String] service identifier
+      # @return [String] task UPID
+      def reload(node, service)
+        post_action(node, service, "reload")
+      end
+
+      protected
+
+      # Builds Service model from API response data.
+      #
+      # @param data [Hash] API response hash
+      # @return [Models::Service] Service model instance
+      def build_model(data)
+        Models::Service.new(data)
+      end
+
+      private
+
+      # POSTs a lifecycle action and extracts the UPID from the response.
+      #
+      # @param node [String] node name
+      # @param service [String] service identifier
+      # @param action [String] one of "start", "stop", "restart", "reload"
+      # @return [String] task UPID
+      def post_action(node, service, action)
+        resp = connection.client["nodes/#{node}/services/#{service}/#{action}"].post({})
+        data = extract_data(resp)
+        data.is_a?(String) ? data : data.to_s
+      end
+
+      # Fetches services for a single node.
+      #
+      # @param node_name [String] node name
+      # @return [Array<Models::Service>] services on that node
+      def services_for_node(node_name)
+        response = connection.client["nodes/#{node_name}/services"].get
+        services_data = unwrap(response)
+        services_data.map { |data| build_model(data.merge(node: node_name)) }
+      rescue StandardError
+        []
+      end
+
+      # Fetches list of online node names.
+      #
+      # @return [Array<String>] online node names
+      def online_nodes
+        response = connection.client["nodes"].get
+        nodes_data = unwrap(response)
+        nodes_data
+          .select { |n| n[:status] == "online" }
+          .map { |n| n[:node] || n[:name] }
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/pvectl/repositories/snapshot.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Repositories
+    # Repository for VM/container snapshots.
+    #
+    # Handles listing snapshots for both QEMU VMs and LXC containers.
+    # Filters out the "current" snapshot which represents the live state.
+    #
+    # @example Listing snapshots for a VM
+    #   repo = Snapshot.new(connection)
+    #   snapshots = repo.list(100, "pve1", :qemu)
+    #   snapshots.each { |s| puts "#{s.name}: #{s.description}" }
+    #
+    # @example Listing snapshots for a container
+    #   snapshots = repo.list(101, "pve1", :lxc)
+    #
+    # @see Pvectl::Models::Snapshot Snapshot model
+    # @see Pvectl::Connection API connection
+    #
+    class Snapshot < Base
+      # Lists all snapshots for a VM or container.
+      #
+      # Uses `/nodes/{node}/qemu/{vmid}/snapshot` for VMs or
+      # `/nodes/{node}/lxc/{vmid}/snapshot` for containers.
+      # Filters out the "current" snapshot which represents live state.
+      #
+      # @param vmid [Integer, String] VM or container identifier
+      # @param node [String] node name where the resource resides
+      # @param resource_type [Symbol] :qemu for VMs, :lxc for containers
+      # @return [Array<Models::Snapshot>] collection of snapshot models
+      def list(vmid, node, resource_type)
+        endpoint = resource_endpoint(resource_type)
+        response = connection.client["nodes/#{node}/#{endpoint}/#{vmid}/snapshot"].get
+
+        response
+          .reject { |s| s[:name] == "current" }
+          .map { |data| build_model(data, vmid, node, resource_type) }
+      rescue StandardError
+        []
+      end
+
+      # Creates a snapshot for a VM or container.
+      #
+      # Uses `POST /nodes/{node}/qemu|lxc/{vmid}/snapshot` with parameters:
+      # - snapname: Name of the snapshot
+      # - description: Optional description
+      # - vmstate: Include VM RAM state (QEMU only, ignored for LXC)
+      #
+      # @param vmid [Integer, String] VM or container identifier
+      # @param node [String] node name where the resource resides
+      # @param resource_type [Symbol] :qemu for VMs, :lxc for containers
+      # @param name [String] name for the snapshot
+      # @param description [String, nil] optional description
+      # @param vmstate [Boolean] include RAM state (QEMU only)
+      # @return [String] UPID of the snapshot creation task
+      def create(vmid, node, resource_type, name:, description: nil, vmstate: false)
+        endpoint = resource_endpoint(resource_type)
+        params = { snapname: name }
+        params[:description] = description if description
+        params[:vmstate] = vmstate if vmstate && resource_type == :qemu
+
+        connection.client["nodes/#{node}/#{endpoint}/#{vmid}/snapshot"].post(params)
+      end
+
+      # Deletes a snapshot.
+      #
+      # Uses `DELETE /nodes/{node}/qemu|lxc/{vmid}/snapshot/{snapname}`.
+      #
+      # @param vmid [Integer, String] VM or container identifier
+      # @param node [String] node name where the resource resides
+      # @param resource_type [Symbol] :qemu for VMs, :lxc for containers
+      # @param snapname [String] name of the snapshot to delete
+      # @param force [Boolean] force deletion even if snapshot is referenced
+      # @return [String] UPID of the delete task
+      def delete(vmid, node, resource_type, snapname, force: false)
+        endpoint = resource_endpoint(resource_type)
+        params = {}
+        params[:force] = true if force
+
+        connection.client["nodes/#{node}/#{endpoint}/#{vmid}/snapshot/#{snapname}"].delete(params)
+      end
+
+      # Rolls back to a snapshot.
+      #
+      # Uses `POST /nodes/{node}/qemu|lxc/{vmid}/snapshot/{snapname}/rollback`.
+      #
+      # @param vmid [Integer, String] VM or container identifier
+      # @param node [String] node name where the resource resides
+      # @param resource_type [Symbol] :qemu for VMs, :lxc for containers
+      # @param snapname [String] name of the snapshot to rollback to
+      # @param start [Boolean] start VM/container after rollback
+      # @return [String] UPID of the rollback task
+      def rollback(vmid, node, resource_type, snapname, start: false)
+        endpoint = resource_endpoint(resource_type)
+        params = {}
+        params[:start] = true if start
+
+        connection.client["nodes/#{node}/#{endpoint}/#{vmid}/snapshot/#{snapname}/rollback"].post(params)
+      end
+
+      private
+
+      # Returns the API endpoint prefix for the resource type.
+      #
+      # @param resource_type [Symbol] :qemu or :lxc
+      # @return [String] "qemu" or "lxc"
+      def resource_endpoint(resource_type)
+        resource_type == :lxc ? "lxc" : "qemu"
+      end
+
+      # Builds Snapshot model from API response data.
+      #
+      # @param data [Hash] API response hash
+      # @param vmid [Integer, String] VM/container ID
+      # @param node [String] node name
+      # @param resource_type [Symbol] :qemu or :lxc
+      # @return [Models::Snapshot] snapshot model instance
+      def build_model(data, vmid, node, resource_type)
+        Models::Snapshot.new(
+          name: data[:name],
+          snaptime: data[:snaptime],
+          description: data[:description],
+          vmstate: data[:vmstate],
+          parent: data[:parent],
+          vmid: vmid,
+          node: node,
+          resource_type: resource_type
+        )
+      end
+    end
+  end
+end

data/lib/pvectl/repositories/storage.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Repositories
+    # Repository for Proxmox cluster storage pools.
+    #
+    # Uses the `/cluster/resources?type=storage` API endpoint for cluster-wide view.
+    # Handles aggregation of shared storage (deduplication by name).
+    #
+    # @example Listing all storage pools
+    #   repo = Storage.new(connection)
+    #   storage_pools = repo.list
+    #   storage_pools.each { |s| puts "#{s.name}: #{s.plugintype}" }
+    #
+    # @example Listing storage on a specific node
+    #   storage_pools = repo.list(node: "pve1")
+    #
+    # @see Pvectl::Models::Storage Storage model
+    # @see Pvectl::Connection API connection
+    #
+    class Storage < Base
+      # Lists all storage pools in the cluster.
+      #
+      # Uses `/cluster/resources?type=storage` endpoint for cluster-wide view.
+      # Aggregates shared storage by keeping first entry per storage name.
+      #
+      # @param node [String, nil] filter by node name
+      # @return [Array<Models::Storage>] collection of Storage models
+      def list(node: nil)
+        response = connection.client["cluster/resources"].get(params: { type: "storage" })
+        storage_data = normalize_response(response)
+
+        # Aggregate shared storage (deduplicate by name, keep first entry)
+        aggregated = aggregate_storage(storage_data)
+
+        # Filter by node if specified
+        if node
+          aggregated = aggregated.select { |data| data[:node] == node || data[:shared] == 1 }
+        end
+
+        aggregated.map { |data| build_model(data) }
+      end
+
+      # Gets a single storage pool by name.
+      #
+      # @param name [String] storage pool name
+      # @return [Models::Storage, nil] Storage model or nil if not found
+      def get(name)
+        list.find { |s| s.name == name }
+      end
+
+      # Lists all instances of a storage by name.
+      #
+      # For shared storage: returns single instance.
+      # For local storage: returns all instances (one per node).
+      #
+      # @param name [String] storage name
+      # @return [Array<Models::Storage>] array of storage instances
+      def list_instances(name)
+        response = connection.client["cluster/resources"].get(params: { type: "storage" })
+        storage_data = normalize_response(response)
+        storage_data.select { |s| s[:storage] == name }.map { |data| build_model(data) }
+      end
+
+      # Gets storage for a specific node.
+      #
+      # @param name [String] storage name
+      # @param node [String] node name
+      # @return [Models::Storage, nil] Storage model or nil if not found
+      def get_for_node(name, node)
+        list_instances(name).find { |s| s.node == node }
+      end
+
+      # Describes a storage with comprehensive details from multiple API endpoints.
+      #
+      # Fetches:
+      # - Basic storage info from cluster resources (via get or get_for_node)
+      # - Configuration from /storage/{name}
+      # - Status from /nodes/{node}/storage/{name}/status
+      # - Content (volumes) from /nodes/{node}/storage/{name}/content
+      #
+      # @param name [String] storage name
+      # @param node [String, nil] specific node for local storage
+      # @return [Models::Storage, nil] Storage model with full details, or nil if not found
+      def describe(name, node: nil)
+        storage = node ? get_for_node(name, node) : get(name)
+        return nil unless storage
+
+        # GET /storage/{name} - configuration
+        config = fetch_storage_config(name)
+
+        # Find active node for this storage
+        node = find_node_for_storage(name, storage)
+
+        # GET /nodes/{node}/storage/{name}/status (if node available)
+        status = node ? fetch_storage_status(node, name) : {}
+
+        # GET /nodes/{node}/storage/{name}/content (volumes)
+        content = node ? fetch_storage_content(node, name) : []
+
+        build_describe_model(storage, config, status, content)
+      end
+
+      # Lists storage pools for a specific node.
+      #
+      # Uses `/nodes/{node}/storage` endpoint which returns detailed
+      # per-node storage information including avail, enabled, active flags.
+      #
+      # @param node_name [String] node name
+      # @return [Array<Models::Storage>] collection of Storage models
+      def list_for_node(node_name)
+        response = connection.client["nodes/#{node_name}/storage"].get
+        storage_data = normalize_response(response)
+
+        storage_data.map { |data| build_model_from_node_api(data, node_name) }
+      end
+
+      protected
+
+      # Builds Storage model from API response data.
+      #
+      # @param data [Hash] API response hash
+      # @return [Models::Storage] Storage model instance
+      def build_model(data)
+        Models::Storage.new(
+          name: data[:storage],
+          plugintype: data[:plugintype],
+          status: data[:status],
+          node: data[:node],
+          disk: data[:disk],
+          maxdisk: data[:maxdisk],
+          content: data[:content],
+          shared: data[:shared]
+        )
+      end
+
+      # Builds Storage model from /nodes/{node}/storage API response.
+      #
+      # Maps node-specific API fields to model attributes:
+      # - type -> plugintype
+      # - used -> disk
+      # - total -> maxdisk
+      # - active -> status (derived)
+      #
+      # @param data [Hash] API response hash
+      # @param node_name [String] node name (not in response, passed as param)
+      # @return [Models::Storage] Storage model instance
+      def build_model_from_node_api(data, node_name)
+        Models::Storage.new(
+          name: data[:storage],
+          plugintype: data[:type],
+          node: node_name,
+          disk: data[:used],
+          maxdisk: data[:total],
+          avail: data[:avail],
+          content: data[:content],
+          enabled: data[:enabled],
+          active: data[:active],
+          shared: 0 # /nodes/{node}/storage doesn't return shared flag
+        )
+      end
+
+      private
+
+      # Fetches storage configuration from /storage/{name}.
+      #
+      # @param name [String] storage name
+      # @return [Hash] configuration data or empty hash on error
+      def fetch_storage_config(name)
+        response = connection.client["storage/#{name}"].get
+        extract_data(response)
+      rescue StandardError
+        {}
+      end
+
+      # Fetches storage status from /nodes/{node}/storage/{name}/status.
+      #
+      # @param node [String] node name
+      # @param name [String] storage name
+      # @return [Hash] status data or empty hash on error
+      def fetch_storage_status(node, name)
+        response = connection.client["nodes/#{node}/storage/#{name}/status"].get
+        extract_data(response)
+      rescue StandardError
+        {}
+      end
+
+      # Fetches storage content (volumes) from /nodes/{node}/storage/{name}/content.
+      #
+      # @param node [String] node name
+      # @param name [String] storage name
+      # @return [Array<Hash>] volumes array or empty array on error
+      def fetch_storage_content(node, name)
+        response = connection.client["nodes/#{node}/storage/#{name}/content"].get
+        unwrap(response)
+      rescue StandardError
+        []
+      end
+
+      # Finds an active node where this storage is accessible.
+      #
+      # For local storage: uses the node it belongs to.
+      # For shared storage: finds first online node in the cluster.
+      #
+      # @param name [String] storage name
+      # @param storage [Models::Storage] storage model
+      # @return [String, nil] node name or nil if unavailable
+      def find_node_for_storage(name, storage)
+        # For local storage, use the node it belongs to
+        return storage.node unless storage.shared?
+
+        # For shared storage, find first available online node
+        nodes_response = connection.client["nodes"].get
+        nodes = unwrap(nodes_response)
+        online_node = nodes.find { |n| n[:status] == "online" }
+        online_node&.dig(:node)
+      rescue StandardError
+        nil
+      end
+
+      # Builds Storage model with comprehensive describe data.
+      #
+      # Merges data from basic storage, config, status, and content endpoints.
+      #
+      # @param storage [Models::Storage] base storage model
+      # @param config [Hash] configuration from /storage/{name}
+      # @param status [Hash] status from /nodes/{node}/storage/{name}/status
+      # @param content [Array<Hash>] volumes from /content endpoint
+      # @return [Models::Storage] complete storage model
+      def build_describe_model(storage, config, status, content)
+        Models::Storage.new(
+          # Basic attributes from list
+          name: storage.name,
+          plugintype: storage.plugintype,
+          status: storage.status,
+          node: storage.node,
+          disk: storage.disk,
+          maxdisk: storage.maxdisk,
+          content: storage.content,
+          shared: storage.shared,
+
+          # Config attributes
+          path: config[:path],
+          server: config[:server],
+          export: config[:export],
+          pool: config[:pool],
+          vgname: config[:vgname],
+          thinpool: config[:thinpool],
+          nodes: config[:nodes],
+          "prune-backups": config[:"prune-backups"],
+          maxfiles: config[:maxfiles],
+
+          # Status attributes (override if available)
+          avail: status[:avail] || storage.avail,
+          enabled: status[:enabled] || storage.enabled,
+          active: status[:active] || storage.active_flag,
+
+          # Content (volumes)
+          volumes: content
+        )
+      end
+
+      # Normalizes API response to array format.
+      #
+      # @param response [Array, Hash] API response
+      # @return [Array<Hash>] array of storage data hashes
+      def normalize_response(response)
+        if response.is_a?(Array)
+          response
+        elsif response.is_a?(Hash) && response[:data]
+          response[:data]
+        else
+          response.to_a
+        end
+      end
+
+      # Aggregates storage data by name.
+      # For shared storage, keeps first entry (data is identical across nodes).
+      # For local storage, keeps all entries.
+      #
+      # @param storage_data [Array<Hash>] raw storage data from API
+      # @return [Array<Hash>] aggregated storage data
+      def aggregate_storage(storage_data)
+        seen = {}
+        storage_data.each do |data|
+          name = data[:storage]
+          next if name.nil?
+
+          # For shared storage, keep only first entry
+          if data[:shared] == 1
+            seen[name] ||= data
+          else
+            # For local storage, include all (unique by name+node)
+            key = "#{name}:#{data[:node]}"
+            seen[key] ||= data
+          end
+        end
+        seen.values
+      end
+    end
+  end
+end

data/lib/pvectl/repositories/subscription.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Repositories
+    # Repository for Proxmox subscription information per node.
+    #
+    # Wraps the `GET /nodes/{node}/subscription` endpoint and aggregates
+    # subscription records across all nodes in the cluster.
+    #
+    # @example Listing subscriptions across the cluster
+    #   repo = Subscription.new(connection)
+    #   repo.list.each { |s| puts "#{s.node}: #{s.status} #{s.level}" }
+    #
+    # @see Pvectl::Models::Subscription
+    #
+    class Subscription < Base
+      # Lists subscription records for cluster nodes.
+      #
+      # Returns one Subscription per online node. Offline / unreachable
+      # nodes return a Subscription with status="unreachable" so the output
+      # remains stable instead of silently dropping rows.
+      #
+      # @param node [String, nil] filter to a single node (otherwise all online nodes)
+      # @return [Array<Models::Subscription>]
+      def list(node: nil)
+        node_names = node ? [node] : online_node_names
+        node_names.map { |name| fetch_for(name) }
+      end
+
+      # Fetches the subscription record for a single node.
+      #
+      # @param node [String] node name
+      # @return [Models::Subscription]
+      def get(node)
+        fetch_for(node)
+      end
+
+      protected
+
+      # Builds a Subscription model from API data plus the node name.
+      #
+      # @param data [Hash] API response payload (already extracted from :data wrapper)
+      # @param node_name [String] node the record belongs to
+      # @return [Models::Subscription]
+      def build_model(data, node_name)
+        attrs = (data || {}).merge(node: node_name)
+        Models::Subscription.new(attrs)
+      end
+
+      private
+
+      # Returns names of all online nodes in the cluster.
+      #
+      # @return [Array<String>]
+      def online_node_names
+        response = connection.client["nodes"].get
+        nodes = unwrap(response)
+        nodes
+          .select { |n| n[:status].nil? || n[:status] == "online" }
+          .map { |n| n[:node] || n[:name] }
+          .compact
+      end
+
+      # Fetches one node's subscription, recovering from API errors gracefully.
+      #
+      # @param node_name [String]
+      # @return [Models::Subscription]
+      def fetch_for(node_name)
+        response = connection.client["nodes/#{node_name}/subscription"].get
+        data = extract_data(response)
+        build_model(data, node_name)
+      rescue StandardError => e
+        build_model({ status: "unreachable", message: e.message }, node_name)
+      end
+    end
+  end
+end

data/lib/pvectl/repositories/syslog.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Repositories
+    # Repository for reading node syslog.
+    # Uses GET /nodes/{node}/syslog endpoint.
+    class Syslog < Base
+      # @param node [String] node name (required)
+      # @param limit [Integer] max entries (default 50)
+      # @param since [String, nil] start timestamp
+      # @param until_time [String, nil] end timestamp
+      # @param service [String, nil] filter by service name
+      # @return [Array<Models::SyslogEntry>]
+      def list(node:, limit: 50, since: nil, until_time: nil, service: nil)
+        params = { limit: limit }
+        params[:since] = since if since
+        params[:until] = until_time if until_time
+        params[:service] = service if service
+
+        response = connection.client["nodes/#{node}/syslog"].get(params: params)
+        models_from(response, Models::SyslogEntry)
+      end
+    end
+  end
+end