pvectl 0.2.0

data/lib/pvectl/config/models/cluster.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Config
+    module Models
+      # Represents a Proxmox cluster server configuration.
+      #
+      # Cluster is an immutable value object containing connection settings
+      # for a single Proxmox server. It stores the server URL, SSL options,
+      # and retry/timeout configuration.
+      #
+      # @example Creating a cluster from constructor
+      #   cluster = Cluster.new(
+      #     name: "production",
+      #     server: "https://pve.example.com:8006",
+      #     verify_ssl: true,
+      #     certificate_authority: "/path/to/ca.crt"
+      #   )
+      #
+      # @example Creating from YAML config hash
+      #   hash = {
+      #     "name" => "production",
+      #     "cluster" => {
+      #       "server" => "https://pve.example.com:8006",
+      #       "insecure-skip-tls-verify" => false
+      #     }
+      #   }
+      #   cluster = Cluster.from_hash(hash)
+      #
+      class Cluster
+        # @return [String] unique name identifying this cluster
+        attr_reader :name
+
+        # @return [String] Proxmox server URL (e.g., "https://pve.example.com:8006")
+        attr_reader :server
+
+        # @return [Boolean] whether to verify SSL certificates
+        attr_reader :verify_ssl
+
+        # @return [String, nil] path to CA certificate file
+        attr_reader :certificate_authority
+
+        # @return [Integer, nil] request timeout in seconds
+        attr_reader :timeout
+
+        # @return [Integer, nil] maximum retry attempts
+        attr_reader :retry_count
+
+        # @return [Integer, nil] base delay between retries in seconds
+        attr_reader :retry_delay
+
+        # @return [Integer, nil] maximum delay cap for exponential backoff
+        attr_reader :max_retry_delay
+
+        # @return [Boolean, nil] whether to retry write operations
+        attr_reader :retry_writes
+
+        # Creates a new Cluster instance.
+        #
+        # @param name [String] unique name for this cluster
+        # @param server [String] Proxmox server URL
+        # @param verify_ssl [Boolean] whether to verify SSL (default: true)
+        # @param certificate_authority [String, nil] path to CA certificate
+        # @param timeout [Integer, nil] request timeout in seconds
+        # @param retry_count [Integer, nil] maximum retry attempts
+        # @param retry_delay [Integer, nil] base delay between retries
+        # @param max_retry_delay [Integer, nil] maximum delay cap
+        # @param retry_writes [Boolean, nil] whether to retry write operations
+        #
+        # @raise [InvalidConfigError] if validation fails
+        def initialize(name:, server:, verify_ssl: true, certificate_authority: nil,
+                       timeout: nil, retry_count: nil, retry_delay: nil,
+                       max_retry_delay: nil, retry_writes: nil)
+          @name = name
+          @server = server
+          @verify_ssl = verify_ssl
+          @certificate_authority = certificate_authority
+          @timeout = timeout
+          @retry_count = retry_count
+          @retry_delay = retry_delay
+          @max_retry_delay = max_retry_delay
+          @retry_writes = retry_writes
+
+          validate_retry_settings!
+        end
+
+        # Creates a Cluster from a kubeconfig-style hash structure.
+        #
+        # @param hash [Hash] hash with "name" and "cluster" keys
+        # @return [Cluster] new cluster instance
+        # @raise [InvalidConfigError] if validation fails
+        #
+        # @example Hash structure
+        #   {
+        #     "name" => "production",
+        #     "cluster" => {
+        #       "server" => "https://pve.example.com:8006",
+        #       "insecure-skip-tls-verify" => true,
+        #       "certificate-authority" => "/path/to/ca.crt"
+        #     }
+        #   }
+        def self.from_hash(hash)
+          cluster_data = hash["cluster"] || {}
+
+          new(
+            name: hash["name"],
+            server: cluster_data["server"],
+            verify_ssl: !cluster_data["insecure-skip-tls-verify"],
+            certificate_authority: cluster_data["certificate-authority"],
+            timeout: cluster_data["timeout"],
+            retry_count: cluster_data["retry-count"],
+            retry_delay: cluster_data["retry-delay"],
+            max_retry_delay: cluster_data["max-retry-delay"],
+            retry_writes: cluster_data["retry-writes"]
+          )
+        end
+
+        # Converts the cluster to a kubeconfig-style hash structure.
+        #
+        # @return [Hash] hash representation suitable for YAML serialization
+        def to_hash
+          cluster_data = {
+            "server" => server,
+            "insecure-skip-tls-verify" => !verify_ssl
+          }
+          cluster_data["certificate-authority"] = certificate_authority if certificate_authority
+          cluster_data["timeout"] = timeout if timeout
+          cluster_data["retry-count"] = retry_count if retry_count
+          cluster_data["retry-delay"] = retry_delay if retry_delay
+          cluster_data["max-retry-delay"] = max_retry_delay if max_retry_delay
+          cluster_data["retry-writes"] = retry_writes unless retry_writes.nil?
+
+          {
+            "name" => name,
+            "cluster" => cluster_data
+          }
+        end
+
+        private
+
+        # Validates retry/timeout settings.
+        #
+        # @raise [InvalidConfigError] if values are invalid
+        def validate_retry_settings!
+          validate_positive(:timeout, @timeout) if @timeout
+          validate_non_negative_integer(:retry_count, @retry_count) if @retry_count
+          validate_positive(:retry_delay, @retry_delay) if @retry_delay
+          validate_positive(:max_retry_delay, @max_retry_delay) if @max_retry_delay
+
+          if @retry_delay && @max_retry_delay && @max_retry_delay < @retry_delay
+            raise InvalidConfigError,
+                  "max-retry-delay (#{@max_retry_delay}) must be >= retry-delay (#{@retry_delay})"
+          end
+        end
+
+        # Validates that a value is a positive number.
+        #
+        # @param name [Symbol] attribute name for error message
+        # @param value [Object] value to validate
+        # @raise [InvalidConfigError] if value is not positive
+        def validate_positive(name, value)
+          return if value.is_a?(Numeric) && value.positive?
+
+          raise InvalidConfigError, "#{name} must be a positive number, got: #{value.inspect}"
+        end
+
+        # Validates that a value is a non-negative integer.
+        #
+        # @param name [Symbol] attribute name for error message
+        # @param value [Object] value to validate
+        # @raise [InvalidConfigError] if value is not a non-negative integer
+        def validate_non_negative_integer(name, value)
+          return if value.is_a?(Integer) && value >= 0
+
+          raise InvalidConfigError, "#{name} must be a non-negative integer, got: #{value.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/config/models/context.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Config
+    module Models
+      # Represents a context linking a cluster to a user.
+      #
+      # Context is an immutable value object that binds together a cluster
+      # and user configuration, similar to kubectl contexts. It optionally
+      # includes a default node for operations.
+      #
+      # @example Creating a context
+      #   context = Context.new(
+      #     name: "production",
+      #     cluster_ref: "pve-prod",
+      #     user_ref: "admin",
+      #     default_node: "pve1"
+      #   )
+      #
+      # @example Creating from YAML config hash
+      #   hash = {
+      #     "name" => "prod",
+      #     "context" => {
+      #       "cluster" => "production",
+      #       "user" => "admin-prod",
+      #       "default-node" => "pve1"
+      #     }
+      #   }
+      #   context = Context.from_hash(hash)
+      #
+      class Context
+        # @return [String] unique name identifying this context
+        attr_reader :name
+
+        # @return [String] reference to cluster name
+        attr_reader :cluster_ref
+
+        # @return [String] reference to user name
+        attr_reader :user_ref
+
+        # @return [String, nil] default node for operations
+        attr_reader :default_node
+
+        # Creates a new Context instance.
+        #
+        # @param name [String] unique name for this context
+        # @param cluster_ref [String] name of the cluster to use
+        # @param user_ref [String] name of the user to use
+        # @param default_node [String, nil] optional default node
+        def initialize(name:, cluster_ref:, user_ref:, default_node: nil)
+          @name = name
+          @cluster_ref = cluster_ref
+          @user_ref = user_ref
+          @default_node = default_node
+        end
+
+        # Creates a Context from a kubeconfig-style hash structure.
+        #
+        # @param hash [Hash] hash with "name" and "context" keys
+        # @return [Context] new context instance
+        #
+        # @example Hash structure
+        #   {
+        #     "name" => "prod",
+        #     "context" => {
+        #       "cluster" => "production",
+        #       "user" => "admin-prod",
+        #       "default-node" => "pve1"
+        #     }
+        #   }
+        def self.from_hash(hash)
+          context_data = hash["context"] || {}
+
+          new(
+            name: hash["name"],
+            cluster_ref: context_data["cluster"],
+            user_ref: context_data["user"],
+            default_node: context_data["default-node"]
+          )
+        end
+
+        # Converts the context to a kubeconfig-style hash structure.
+        #
+        # @return [Hash] hash representation suitable for YAML serialization
+        def to_hash
+          context_data = {
+            "cluster" => cluster_ref,
+            "user" => user_ref
+          }
+          context_data["default-node"] = default_node if default_node
+
+          {
+            "name" => name,
+            "context" => context_data
+          }
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/config/models/resolved_config.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Config
+    module Models
+      # Represents the final resolved configuration ready for use.
+      #
+      # ResolvedConfig is an immutable value object containing all settings
+      # needed to connect to a Proxmox server. It is created by merging
+      # configuration from file, environment variables, and CLI options.
+      #
+      # @example Creating a resolved config with token auth
+      #   config = ResolvedConfig.new(
+      #     context_name: "production",
+      #     server: "https://pve.example.com:8006",
+      #     auth_type: :token,
+      #     token_id: "root@pam!automation",
+      #     token_secret: "secret-uuid"
+      #   )
+      #
+      # @example Getting connection options for proxmox-api gem
+      #   options = config.to_connection_options
+      #   # => { server: "https://...", token: "root@pam!automation", ... }
+      #
+      class ResolvedConfig
+        # Default values for retry/timeout settings
+        DEFAULT_TIMEOUT = 30
+        DEFAULT_RETRY_COUNT = 3
+        DEFAULT_RETRY_DELAY = 1
+        DEFAULT_MAX_RETRY_DELAY = 30
+        DEFAULT_RETRY_WRITES = false
+
+        # @return [String] name of the active context
+        attr_reader :context_name
+
+        # @return [String] Proxmox server URL
+        attr_reader :server
+
+        # @return [Boolean] whether to verify SSL certificates
+        attr_reader :verify_ssl
+
+        # @return [String, nil] path to CA certificate file
+        attr_reader :certificate_authority
+
+        # @return [Symbol] authentication type (:token or :password)
+        attr_reader :auth_type
+
+        # @return [String, nil] API token ID
+        attr_reader :token_id
+
+        # @return [String, nil] API token secret
+        attr_reader :token_secret
+
+        # @return [String, nil] username for password auth
+        attr_reader :username
+
+        # @return [String, nil] password for password auth
+        attr_reader :password
+
+        # @return [String, nil] default node for operations
+        attr_reader :default_node
+
+        # @return [Integer] request timeout in seconds
+        attr_reader :timeout
+
+        # @return [Integer] maximum retry attempts
+        attr_reader :retry_count
+
+        # @return [Integer] base delay between retries in seconds
+        attr_reader :retry_delay
+
+        # @return [Integer] maximum delay cap for exponential backoff
+        attr_reader :max_retry_delay
+
+        # @return [Boolean] whether to retry write operations
+        attr_reader :retry_writes
+
+        # Creates a new ResolvedConfig instance.
+        #
+        # @param context_name [String] name of the active context
+        # @param server [String] Proxmox server URL
+        # @param auth_type [Symbol] :token or :password
+        # @param verify_ssl [Boolean] whether to verify SSL (default: true)
+        # @param certificate_authority [String, nil] path to CA certificate
+        # @param token_id [String, nil] API token ID (required for :token auth)
+        # @param token_secret [String, nil] API token secret (required for :token auth)
+        # @param username [String, nil] username (required for :password auth)
+        # @param password [String, nil] password (required for :password auth)
+        # @param default_node [String, nil] default node for operations
+        # @param timeout [Integer, nil] request timeout (default: 30)
+        # @param retry_count [Integer, nil] max retries (default: 3)
+        # @param retry_delay [Integer, nil] base delay (default: 1)
+        # @param max_retry_delay [Integer, nil] max delay cap (default: 30)
+        # @param retry_writes [Boolean, nil] retry writes (default: false)
+        def initialize(context_name:, server:, auth_type:, verify_ssl: true,
+                       certificate_authority: nil, token_id: nil, token_secret: nil,
+                       username: nil, password: nil, default_node: nil,
+                       timeout: nil, retry_count: nil, retry_delay: nil,
+                       max_retry_delay: nil, retry_writes: nil)
+          @context_name = context_name
+          @server = server
+          @verify_ssl = verify_ssl
+          @certificate_authority = certificate_authority
+          @auth_type = auth_type
+          @token_id = token_id
+          @token_secret = token_secret
+          @username = username
+          @password = password
+          @default_node = default_node
+
+          # Apply defaults for retry/timeout settings
+          @timeout = timeout || DEFAULT_TIMEOUT
+          @retry_count = retry_count || DEFAULT_RETRY_COUNT
+          @retry_delay = retry_delay || DEFAULT_RETRY_DELAY
+          @max_retry_delay = max_retry_delay || DEFAULT_MAX_RETRY_DELAY
+          @retry_writes = retry_writes.nil? ? DEFAULT_RETRY_WRITES : retry_writes
+        end
+
+        # Checks if this config uses API token authentication.
+        #
+        # @return [Boolean] true if auth_type is :token
+        def token_auth?
+          auth_type == :token
+        end
+
+        # Checks if this config uses password authentication.
+        #
+        # @return [Boolean] true if auth_type is :password
+        def password_auth?
+          auth_type == :password
+        end
+
+        # Converts the config to options hash for proxmox-api gem.
+        #
+        # @return [Hash] options for ProxmoxAPI.new
+        #
+        # @example Token auth options
+        #   {
+        #     server: "https://pve.example.com:8006",
+        #     token: "root@pam!automation",
+        #     secret: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+        #     verify_ssl: false
+        #   }
+        #
+        # @example Password auth options
+        #   {
+        #     server: "https://pve.example.com:8006",
+        #     username: "root@pam",
+        #     password: "secret",
+        #     verify_ssl: true
+        #   }
+        def to_connection_options
+          options = {
+            server: server,
+            verify_ssl: verify_ssl
+          }
+
+          if token_auth?
+            options[:token] = token_id
+            options[:secret] = token_secret
+          else
+            options[:username] = username
+            options[:password] = password
+          end
+
+          options
+        end
+      end
+    end
+  end
+end

data/lib/pvectl/config/models/user.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Config
+    module Models
+      # Represents user credentials for Proxmox API authentication.
+      #
+      # User is an immutable value object supporting two authentication methods:
+      # - API Token authentication (token_id + token_secret)
+      # - Username/Password authentication (username + password)
+      #
+      # @example Creating a user with token authentication
+      #   user = User.new(
+      #     name: "admin",
+      #     token_id: "root@pam!automation",
+      #     token_secret: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+      #   )
+      #   user.token_auth? #=> true
+      #
+      # @example Creating a user with password authentication
+      #   user = User.new(
+      #     name: "admin",
+      #     username: "root@pam",
+      #     password: "secret"
+      #   )
+      #   user.password_auth? #=> true
+      #
+      class User
+        # Mask used to hide secrets in output
+        SECRET_MASK = "********"
+
+        # @return [String] unique name identifying this user
+        attr_reader :name
+
+        # @return [String, nil] API token ID (e.g., "root@pam!tokenid")
+        attr_reader :token_id
+
+        # @return [String, nil] API token secret (UUID format)
+        attr_reader :token_secret
+
+        # @return [String, nil] username for password auth (e.g., "root@pam")
+        attr_reader :username
+
+        # @return [String, nil] password for password auth
+        attr_reader :password
+
+        # Creates a new User instance.
+        #
+        # @param name [String] unique name for this user
+        # @param token_id [String, nil] API token ID
+        # @param token_secret [String, nil] API token secret
+        # @param username [String, nil] username for password auth
+        # @param password [String, nil] password for password auth
+        def initialize(name:, token_id: nil, token_secret: nil, username: nil, password: nil)
+          @name = name
+          @token_id = token_id
+          @token_secret = token_secret
+          @username = username
+          @password = password
+        end
+
+        # Checks if this user is configured for API token authentication.
+        #
+        # @return [Boolean] true if both token_id and token_secret are present
+        def token_auth?
+          !token_id.nil? && !token_id.empty? && !token_secret.nil? && !token_secret.empty?
+        end
+
+        # Checks if this user is configured for password authentication.
+        #
+        # @return [Boolean] true if both username and password are present
+        def password_auth?
+          !username.nil? && !username.empty? && !password.nil? && !password.empty?
+        end
+
+        # Checks if this user has valid credentials for authentication.
+        #
+        # @return [Boolean] true if token auth or password auth is configured
+        def valid?
+          token_auth? || password_auth?
+        end
+
+        # Creates a User from a kubeconfig-style hash structure.
+        #
+        # @param hash [Hash] hash with "name" and "user" keys
+        # @return [User] new user instance
+        #
+        # @example Hash structure for token auth
+        #   {
+        #     "name" => "admin",
+        #     "user" => {
+        #       "token-id" => "root@pam!token",
+        #       "token-secret" => "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+        #     }
+        #   }
+        def self.from_hash(hash)
+          user_data = hash["user"] || {}
+
+          new(
+            name: hash["name"],
+            token_id: user_data["token-id"],
+            token_secret: user_data["token-secret"],
+            username: user_data["username"],
+            password: user_data["password"]
+          )
+        end
+
+        # Converts the user to a kubeconfig-style hash structure.
+        #
+        # @param mask_secrets [Boolean] whether to mask sensitive values
+        # @return [Hash] hash representation suitable for YAML serialization
+        def to_hash(mask_secrets: false)
+          user_data = {}
+
+          if token_auth?
+            user_data["token-id"] = token_id
+            user_data["token-secret"] = mask_secrets ? SECRET_MASK : token_secret
+          end
+
+          if password_auth?
+            user_data["username"] = username
+            user_data["password"] = mask_secrets ? SECRET_MASK : password
+          end
+
+          {
+            "name" => name,
+            "user" => user_data
+          }
+        end
+      end
+    end
+  end
+end