pvectl 0.2.0

data/lib/pvectl/connection/retry_handler.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "rest-client"
+require "timeout"
+
+module Pvectl
+  class Connection
+    # Handles retry logic with exponential backoff for API requests.
+    #
+    # RetryHandler wraps API calls to automatically retry on transient errors
+    # like network timeouts, server errors (5xx), and rate limiting (429).
+    # By default, only read operations (GET) are retried; write operations
+    # require explicit opt-in via retry_writes due to idempotency concerns.
+    #
+    # @example Basic usage with read operation
+    #   handler = RetryHandler.new(max_retries: 3, base_delay: 1, max_delay: 30)
+    #   result = handler.with_retry(method: :get) { api.nodes.get }
+    #
+    # @example Write operation with retries disabled (default)
+    #   handler.with_retry(method: :post) { api.nodes[node].qemu.post(data) }
+    #   # Will NOT retry on failure
+    #
+    # @example Write operation with retries enabled
+    #   handler = RetryHandler.new(max_retries: 3, base_delay: 1, max_delay: 30, retry_writes: true)
+    #   handler.with_retry(method: :post) { api.nodes[node].qemu.post(data) }
+    #   # Will retry on transient failures
+    #
+    class RetryHandler
+      # Exceptions that indicate transient failures safe to retry.
+      #
+      # Includes:
+      # - Connection timeouts (OpenTimeout, ReadTimeout)
+      # - Server errors (5xx)
+      # - Rate limiting (429)
+      # - Network errors (ECONNREFUSED, ECONNRESET, SocketError)
+      # - Global timeout (Timeout::Error from Ruby's Timeout module)
+      RETRYABLE_EXCEPTIONS = [
+        RestClient::Exceptions::OpenTimeout,
+        RestClient::Exceptions::ReadTimeout,
+        RestClient::InternalServerError,     # 500
+        RestClient::BadGateway,              # 502
+        RestClient::ServiceUnavailable,      # 503
+        RestClient::GatewayTimeout,          # 504
+        RestClient::TooManyRequests,         # 429
+        Errno::ECONNREFUSED,
+        Errno::ECONNRESET,
+        SocketError,
+        Timeout::Error
+      ].freeze
+
+      # HTTP methods considered safe to retry (read-only, idempotent).
+      READ_METHODS = %i[get head options].freeze
+
+      # @return [Integer] maximum number of retry attempts
+      attr_reader :max_retries
+
+      # @return [Numeric] base delay in seconds for exponential backoff
+      attr_reader :base_delay
+
+      # @return [Numeric] maximum delay cap in seconds
+      attr_reader :max_delay
+
+      # @return [Boolean] whether to retry write operations
+      attr_reader :retry_writes
+
+      # @return [Logger, nil] optional logger for retry messages
+      attr_reader :logger
+
+      # Creates a new RetryHandler.
+      #
+      # @param max_retries [Integer] maximum number of retry attempts (0 = no retries)
+      # @param base_delay [Numeric] base delay in seconds for exponential backoff
+      # @param max_delay [Numeric] maximum delay cap in seconds
+      # @param retry_writes [Boolean] whether to retry write operations (default: false)
+      # @param logger [Logger, nil] optional logger for retry messages
+      def initialize(max_retries:, base_delay:, max_delay:, retry_writes: false, logger: nil)
+        @max_retries = max_retries
+        @base_delay = base_delay
+        @max_delay = max_delay
+        @retry_writes = retry_writes
+        @logger = logger
+      end
+
+      # Executes a block with retry logic.
+      #
+      # Retries the block on transient errors using exponential backoff.
+      # By default, only read operations (GET, HEAD, OPTIONS) are retried.
+      # Write operations require retry_writes: true in the constructor.
+      #
+      # @param method [Symbol] HTTP method (:get, :post, :put, :delete, :head, :options)
+      # @yield the API call to execute
+      # @return [Object] result of the block
+      # @raise [Exception] the last error after all retries exhausted
+      #
+      # @example
+      #   handler.with_retry(method: :get) { api.nodes.get }
+      def with_retry(method: :get)
+        attempts = 0
+        begin
+          attempts += 1
+          yield
+        rescue *RETRYABLE_EXCEPTIONS => e
+          raise unless should_retry?(method, attempts)
+
+          delay = calculate_delay(attempts)
+          log_retry(attempts, delay, e)
+          sleep(delay)
+          retry
+        end
+      end
+
+      private
+
+      # Determines if the operation should be retried.
+      #
+      # @param method [Symbol] HTTP method
+      # @param attempts [Integer] current attempt count (1-based)
+      # @return [Boolean] true if retry should be attempted
+      def should_retry?(method, attempts)
+        return false if attempts > max_retries
+        return true if READ_METHODS.include?(method)
+
+        retry_writes
+      end
+
+      # Calculates delay using exponential backoff.
+      #
+      # Formula: delay = min(base_delay * 2^(attempt-1), max_delay)
+      #
+      # Example with base_delay=1, max_delay=30:
+      # - Attempt 1: 1s
+      # - Attempt 2: 2s
+      # - Attempt 3: 4s
+      # - Attempt 4: 8s
+      # - Attempt 5+: capped at 30s
+      #
+      # @param attempt [Integer] current attempt number (1-based)
+      # @return [Numeric] delay in seconds
+      def calculate_delay(attempt)
+        delay = base_delay * (2**(attempt - 1))
+        [delay, max_delay].min
+      end
+
+      # Logs a retry attempt.
+      #
+      # Security: Only logs error class name, NOT error.message which may
+      # contain sensitive data (URLs with tokens, request bodies, etc.)
+      #
+      # @param attempt [Integer] current attempt number
+      # @param delay [Numeric] delay before next attempt
+      # @param error [Exception] the error that triggered the retry
+      def log_retry(attempt, delay, error)
+        return unless logger
+
+        logger.warn(
+          "Retry #{attempt}/#{max_retries} after #{delay}s: #{error.class.name}"
+        )
+      end
+    end
+  end
+end

data/lib/pvectl/connection.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "proxmox_api"
+require "timeout"
+require_relative "connection/retry_handler"
+
+module Pvectl
+  # Wrapper for Proxmox API communication.
+  #
+  # Connection encapsulates the proxmox-api gem client, providing a unified
+  # interface for API access. It handles both token and password authentication,
+  # and includes retry logic with exponential backoff and timeout handling.
+  #
+  # @example Creating a connection with ResolvedConfig
+  #   config = service.current_config
+  #   connection = Connection.new(config)
+  #   connection.verify!
+  #   client = connection.client
+  #
+  # @example Checking API version
+  #   version = connection.version
+  #   puts "Proxmox VE #{version['release']}"
+  #
+  # @example Creating a connection with logging
+  #   logger = Logger.new($stderr)
+  #   connection = Connection.new(config, logger: logger)
+  #
+  class Connection
+    # @return [Config::Models::ResolvedConfig] the configuration used
+    attr_reader :config
+
+    # @return [Connection::RetryHandler] the retry handler instance
+    attr_reader :retry_handler
+
+    # Creates a new Connection instance.
+    #
+    # @param config [Config::Models::ResolvedConfig] resolved configuration
+    # @param logger [Logger, nil] optional logger for retry messages
+    def initialize(config, logger: nil)
+      @config = config
+      @client = nil
+      @logger = logger
+      @retry_handler = RetryHandler.new(
+        max_retries: config.retry_count,
+        base_delay: config.retry_delay,
+        max_delay: config.max_retry_delay,
+        retry_writes: config.retry_writes,
+        logger: logger
+      )
+    end
+
+    # Returns the Proxmox API client, creating it if necessary.
+    #
+    # @return [ProxmoxAPI] API client instance
+    def client
+      @client ||= create_client
+    end
+
+    # Verifies the connection to the Proxmox server.
+    #
+    # Makes a test request to the API version endpoint to verify
+    # connectivity and authentication. Uses retry logic for resilience.
+    #
+    # @return [void]
+    # @raise [RuntimeError] if connection fails
+    # @raise [Timeout::Error] if request times out
+    def verify!
+      version
+    end
+
+    # Gets the Proxmox server version information.
+    #
+    # @return [Hash] version information including 'release', 'version', 'repoid'
+    # @raise [Timeout::Error] if request times out
+    def version
+      with_timeout do
+        retry_handler.with_retry(method: :get) do
+          client.version.get
+        end
+      end
+    end
+
+    private
+
+    # Wraps a block with global timeout.
+    #
+    # Uses Ruby's Timeout module since proxmox-api gem doesn't support
+    # timeout options directly.
+    #
+    # @yield block to execute
+    # @return [Object] result of the block
+    # @raise [Timeout::Error] if timeout exceeded
+    def with_timeout
+      Timeout.timeout(config.timeout) do
+        yield
+      end
+    end
+
+    # Creates the Proxmox API client based on configuration.
+    #
+    # @return [ProxmoxAPI] configured API client
+    def create_client
+      host = extract_host
+      options = build_client_options
+
+      if config.token_auth?
+        ProxmoxAPI.new(
+          host,
+          token: config.token_id,
+          secret: config.token_secret,
+          **options
+        )
+      else
+        # Extract username and realm from full username (e.g., "root@pam" -> "root", "pam")
+        username, realm = parse_username(config.username)
+
+        ProxmoxAPI.new(
+          host,
+          username: username,
+          password: config.password,
+          realm: realm,
+          **options
+        )
+      end
+    end
+
+    # Extracts the host from the server URL.
+    #
+    # @return [String] hostname or IP with optional port
+    def extract_host
+      uri = URI.parse(config.server)
+      host = uri.host
+      host = "#{host}:#{uri.port}" if uri.port && uri.port != 8006
+      host
+    end
+
+    # Builds client options hash.
+    #
+    # @return [Hash] options for ProxmoxAPI
+    def build_client_options
+      { verify_ssl: config.verify_ssl }
+    end
+
+    # Parses username into username and realm components.
+    #
+    # @param full_username [String] username with realm (e.g., "root@pam")
+    # @return [Array<String, String>] [username, realm]
+    def parse_username(full_username)
+      if full_username.include?("@")
+        parts = full_username.split("@", 2)
+        [parts[0], parts[1]]
+      else
+        [full_username, "pam"]
+      end
+    end
+  end
+end