Class: Pvectl::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/pvectl/connection.rb,
lib/pvectl/connection/retry_handler.rb,
sig/pvectl/connection.rbs,
sig/pvectl/connection/retry_handler.rbs

Overview

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.

Examples:

Creating a connection with ResolvedConfig

config = service.current_config
connection = Connection.new(config)
connection.verify!
client = connection.client

Checking API version

version = connection.version
puts "Proxmox VE #{version['release']}"

Creating a connection with logging

logger = Logger.new($stderr)
connection = Connection.new(config, logger: logger)

Defined Under Namespace

Classes: RetryHandler

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config, logger: nil) ⇒ Connection

Creates a new Connection instance.

Parameters:

  • resolved configuration

  • (defaults to: nil)

    optional logger for retry messages

  • (defaults to: nil) 


39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/pvectl/connection.rb', line 39

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

Instance Attribute Details

#config ⇒ Config::Models::ResolvedConfig (readonly)

Returns the configuration used.

Returns:

  • the configuration used



30
31
32
 
# File 'lib/pvectl/connection.rb', line 30

def config
  @config
end

#retry_handler ⇒ Connection::RetryHandler (readonly)

Returns the retry handler instance.

Returns:

  • the retry handler instance



33
34
35
 
# File 'lib/pvectl/connection.rb', line 33

def retry_handler
  @retry_handler
end

Instance Method Details

#build_client_options ⇒ Hash

Builds client options hash.

Returns:

  • options for ProxmoxAPI



140
141
142
 
# File 'lib/pvectl/connection.rb', line 140

def build_client_options
  { verify_ssl: config.verify_ssl }
end

#client ⇒ ProxmoxAPI

Returns the Proxmox API client, creating it if necessary.

Returns:

  • API client instance



55
56
57
 
# File 'lib/pvectl/connection.rb', line 55

def client
  @client ||= create_client
end

#create_client ⇒ ProxmoxAPI

Creates the Proxmox API client based on configuration.

Returns:

  • configured API client



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/pvectl/connection.rb', line 102

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

#extract_host ⇒ String

Extracts the host from the server URL.

Returns:

  • hostname or IP with optional port



130
131
132
133
134
135
 
# File 'lib/pvectl/connection.rb', line 130

def extract_host
  uri = URI.parse(config.server)
  host = uri.host
  host = "#{host}:#{uri.port}" if uri.port && uri.port != 8006
  host
end

#parse_username(full_username) ⇒ Array<String, String>

Parses username into username and realm components.

Parameters:

  • username with realm (e.g., "root@pam")

Returns:

  • [username, realm]



148
149
150
151
152
153
154
155
 
# File 'lib/pvectl/connection.rb', line 148

def parse_username(full_username)
  if full_username.include?("@")
    parts = full_username.split("@", 2)
    [parts[0], parts[1]]
  else
    [full_username, "pam"]
  end
end

#verify! ⇒ void

This method returns an undefined value.

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.

Raises:

  • if connection fails

  • if request times out



67
68
69
 
# File 'lib/pvectl/connection.rb', line 67

def verify!
  version
end

#version ⇒ Hash

Gets the Proxmox server version information.

Returns:

  • version information including 'release', 'version', 'repoid'

Raises:

  • if request times out



75
76
77
78
79
80
81
 
# File 'lib/pvectl/connection.rb', line 75

def version
  with_timeout do
    retry_handler.with_retry(method: :get) do
      client.version.get
    end
  end
end

#with_timeout { ... } ⇒ Object

Wraps a block with global timeout.

Uses Ruby's Timeout module since proxmox-api gem doesn't support timeout options directly.

Yields:

  • block to execute

Returns:

  • result of the block

Raises:

  • if timeout exceeded



93
94
95
96
97
 
# File 'lib/pvectl/connection.rb', line 93

def with_timeout
  Timeout.timeout(config.timeout) do
    yield
  end
end