Class: Pvectl::Commands::Ping

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

Overview

Handler for the pvectl ping command.

Verifies connectivity to the Proxmox cluster by calling the version endpoint and measuring response time. Provides a quick health check without detailed resource information.

Examples:

Basic usage

pvectl ping
# Output: OK - Connected to pve1.example.com

Wide output with latency

pvectl ping -o wide
# Output: OK - Connected to pve1.example.com | Latency: 45ms

JSON output for scripts

pvectl ping -o json
# Output: {"status":"ok","server":"pve1.example.com","latency_ms":45}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(global_options) ⇒ Ping

Creates a new Ping command instance.



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

def initialize(global_options)
  @global_options = global_options
  @output_format = global_options[:output] || "table"
  @color_flag = global_options[:color]
  @config = nil
end

Instance Attribute Details

#color_flag ⇒ Boolean? (readonly)

Returns the value of attribute color_flag.



117
118
119
 
# File 'lib/pvectl/commands/ping.rb', line 117

def color_flag
  @color_flag
end

#global_options ⇒ Hash[Symbol, untyped] (readonly)

Returns the value of attribute global_options.



117
118
119
 
# File 'lib/pvectl/commands/ping.rb', line 117

def global_options
  @global_options
end

#output_format ⇒ String (readonly)

Returns the value of attribute output_format.



117
118
119
 
# File 'lib/pvectl/commands/ping.rb', line 117

def output_format
  @output_format
end

Class Method Details

.execute(global_options) ⇒ Integer

Executes the ping command.



69
70
71
 
# File 'lib/pvectl/commands/ping.rb', line 69

def self.execute(global_options)
  new(global_options).execute
end

.register(cli) ⇒ void

This method returns an undefined value.

Registers the ping command with the CLI.



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/pvectl/commands/ping.rb', line 28

def self.register(cli)
  cli.desc "Check connectivity to Proxmox cluster"
  cli.long_desc "    Verify connectivity to the Proxmox cluster by calling the version\n    API endpoint and measuring response time.\n\n    EXAMPLES\n      Basic connectivity check:\n        $ pvectl ping\n\n      Wide output with latency:\n        $ pvectl ping -o wide\n\n      JSON output for scripting:\n        $ pvectl ping -o json\n\n    NOTES\n      Uses the configured context (or PROXMOX_HOST environment variable)\n      to determine which server to ping.\n\n      Exit code 0 = connected, exit code 4 = connection error.\n\n    SEE ALSO\n      pvectl help config          Manage cluster configuration\n      pvectl help get nodes       List cluster nodes\n  HELP\n  cli.command :ping do |c|\n    c.action do |global_options, _options, _args|\n      exit_code = execute(global_options)\n      exit exit_code if exit_code != 0\n    end\n  end\nend\n"

Instance Method Details

#execute ⇒ Integer

Executes the ping operation.



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/pvectl/commands/ping.rb', line 86

def execute
  load_config
  connection = Pvectl::Connection.new(@config)

  result = measure_ping(connection)
  output_result(result, @config.server)

  ExitCodes::SUCCESS
rescue Pvectl::Config::ConfigNotFoundError,
       Pvectl::Config::InvalidConfigError,
       Pvectl::Config::ContextNotFoundError,
       Pvectl::Config::ClusterNotFoundError,
       Pvectl::Config::UserNotFoundError => e
  # Re-raise config errors to be handled by CLI error handler
  raise
rescue Timeout::Error
  output_error("Connection timed out", server_url)
  ExitCodes::CONNECTION_ERROR
rescue Errno::ECONNREFUSED
  output_error("Connection refused", server_url)
  ExitCodes::CONNECTION_ERROR
rescue SocketError => e
  output_error(e.message, server_url)
  ExitCodes::CONNECTION_ERROR
rescue StandardError => e
  output_error(e.message, server_url)
  ExitCodes::CONNECTION_ERROR
end

#extract_host(server_url) ⇒ String

Extracts hostname from server URL.



241
242
243
244
245
246
 
# File 'lib/pvectl/commands/ping.rb', line 241

def extract_host(server_url)
  uri = URI.parse(server_url)
  uri.host
rescue StandardError
  server_url
end

#load_config ⇒ Config::Models::ResolvedConfig

Loads configuration from service.

Raises:



123
124
125
126
127
 
# File 'lib/pvectl/commands/ping.rb', line 123

def load_config
  service = Pvectl::Config::Service.new
  service.load(config: global_options[:config])
  @config = service.current_config
end

#measure_ping(connection) ⇒ Hash

Measures ping latency by timing the version API call.



140
141
142
143
144
145
146
147
148
 
# File 'lib/pvectl/commands/ping.rb', line 140

def measure_ping(connection)
  start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  connection.version
  end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)

  {
    latency_ms: ((end_time - start_time) * 1000).round
  }
end

#output_error(message, server) ⇒ void

This method returns an undefined value.

Outputs error message.



221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/pvectl/commands/ping.rb', line 221

def output_error(message, server)
  pastel = Formatters::ColorSupport.pastel(explicit_flag: color_flag)
  host = extract_host(server)

  case output_format
  when "json"
    require "json"
    puts JSON.pretty_generate({ status: "error", server: host, error: message })
  when "yaml"
    require "yaml"
    puts YAML.dump({ "status" => "error", "server" => host, "error" => message })
  else
    $stderr.puts "#{pastel.red('ERROR')} - Cannot connect to #{host}: #{message}"
  end
end

#output_json(result, server) ⇒ void

This method returns an undefined value.

Outputs JSON format.



193
194
195
196
197
198
199
200
 
# File 'lib/pvectl/commands/ping.rb', line 193

def output_json(result, server)
  require "json"
  puts JSON.pretty_generate({
    status: "ok",
    server: extract_host(server),
    latency_ms: result[:latency_ms]
  })
end

#output_result(result, server) ⇒ void

This method returns an undefined value.

Outputs the result based on the selected format.



155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/pvectl/commands/ping.rb', line 155

def output_result(result, server)
  case output_format
  when "json"
    output_json(result, server)
  when "yaml"
    output_yaml(result, server)
  when "wide"
    output_wide(result, server)
  else
    output_simple(server)
  end
end

#output_simple(server) ⇒ void

This method returns an undefined value.

Outputs simple text format.



172
173
174
175
 
# File 'lib/pvectl/commands/ping.rb', line 172

def output_simple(server)
  pastel = Formatters::ColorSupport.pastel(explicit_flag: color_flag)
  puts "#{pastel.green('OK')} - Connected to #{extract_host(server)}"
end

#output_wide(result, server) ⇒ void

This method returns an undefined value.

Outputs wide text format with latency.



182
183
184
185
186
 
# File 'lib/pvectl/commands/ping.rb', line 182

def output_wide(result, server)
  pastel = Formatters::ColorSupport.pastel(explicit_flag: color_flag)
  puts "#{pastel.green('OK')} - Connected to #{extract_host(server)} | " \
       "Latency: #{result[:latency_ms]}ms"
end

#output_yaml(result, server) ⇒ void

This method returns an undefined value.

Outputs YAML format.



207
208
209
210
211
212
213
214
 
# File 'lib/pvectl/commands/ping.rb', line 207

def output_yaml(result, server)
  require "yaml"
  puts YAML.dump({
    "status" => "ok",
    "server" => extract_host(server),
    "latency_ms" => result[:latency_ms]
  })
end

#server_url ⇒ String

Returns the server URL, or "unknown" if config not loaded.



132
133
134
 
# File 'lib/pvectl/commands/ping.rb', line 132

def server_url
  @config&.server || "unknown"
end