class OvirtSDK4::Probe

This class is used to probe the engine to find which API versions it supports.

Constants

PATH_CANDIDATES

We will only check these paths, as there is where the API is available in common installations of the engine.

Public Class Methods

new(opts) click to toggle source

Creates a new probe.

@param opts [Hash] The options used to create the probe.

@option opts [String] :host The name or IP address of the host to probe.

@option opts [Integer] :port (443) The port number to probe.

@option opts [String] :username The name of the user, something like `admin@internal`.

@option opts [String] :password The password of the user.

@option opts [Boolean] :insecure (false) A boolean flag that indicates if the server TLS certificate and host

name should be checked.

@option opts [String] :ca_file The name of a PEM file containing the trusted CA certificates. The certificate

presented by the server will be verified using these CA certificates. If not set then the system wide CA
certificates store is used.

@option opts [String] :log The logger where the log messages will be written.

@option opts [Boolean] :debug (false) A boolean flag indicating if debug output should be generated. If the

values is `true` and the `log` parameter isn't `nil` then the data sent to and received from the server will
be written to the log. Be aware that user names and passwords will also be written, so handle with care.

@option opts [String] :proxy_url A string containing the protocol, address and port number of the proxy server

to use to connect to the server. For example, in order to use the HTTP proxy `proxy.example.com` that is
listening on port `3128` the value should be `http://proxy.example.com:3128`. This is optional, and if not
given the connection will go directly to the server specified in the `url` parameter.

@option opts [String] :proxy_username The name of the user to authenticate to the proxy server.

@option opts [String] :proxy_password The password of the user to authenticate to the proxy server.

@api private

# File lib/ovirtsdk4/probe.rb, line 107
def initialize(opts)
  # Get the options and assign default values:
  @host           = opts[:host]
  @port           = opts[:port] || 443
  @username       = opts[:username]
  @password       = opts[:password]
  @insecure       = opts[:insecure] || false
  @ca_file        = opts[:ca_file]
  @log            = opts[:log]
  @debug          = opts[:debug] || false
  @proxy_url      = opts[:proxy_url]
  @proxy_username = opts[:proxy_username]
  @proxy_password = opts[:proxy_password]

  # Create the HTTP client:
  @client = HttpClient.new(
    host:           @host,
    port:           @port,
    insecure:       @insecure,
    ca_file:        @ca_file,
    log:            @log,
    debug:          @debug,
    proxy_url:      @proxy_url,
    proxy_username: @proxy_username,
    proxy_password: @proxy_password
  )
end
probe(opts) click to toggle source

This class method receives a set of options that define the server to probe and returns an arrays of objects of the OvirtSDK4::ProbeResult class containing the results of the probe.

@param opts [Hash] The options used to create the probe.

@option opts [String] :host The name or IP address of the host to probe.

@option opts [Integer] :port (443) The port number to probe.

@option opts [String] :username The name of the user, something like `admin@internal`.

@option opts [String] :password The password of the user.

@option opts [Boolean] :insecure (false) A boolean flag that indicates if the server TLS certificate and host

name should be checked.

@option opts [String] :ca_file The name of a PEM file containing the trusted CA certificates. The certificate

presented by the server will be verified using these CA certificates. If not set then the system wide CA
certificates store is used.

@option opts [String] :log The logger where the log messages will be written.

@option opts [Boolean] :debug (false) A boolean flag indicating if debug output should be generated. If the

values is `true` and the `log` parameter isn't `nil` then the data sent to and received from the server will
be written to the log. Be aware that user names and passwords will also be written, so handle with care.

@option opts [String] :proxy_url A string containing the protocol, address and port number of the proxy server

to use to connect to the server. For example, in order to use the HTTP proxy `proxy.example.com` that is
listening on port `3128` the value should be `http://proxy.example.com:3128`. This is optional, and if not
given the connection will go directly to the server specified in the `url` parameter.

@option opts [String] :proxy_username The name of the user to authenticate to the proxy server.

@option opts [String] :proxy_password The password of the user to authenticate to the proxy server.

@return [Array<ProbeResult>] An array of objects of the OvirtSDK4::ProbeResult class.

# File lib/ovirtsdk4/probe.rb, line 60
def self.probe(opts)
  probe = nil
  begin
    probe = Probe.new(opts)
    probe.probe
  ensure
    probe.close if probe
  end
end

Public Instance Methods

close() click to toggle source

Releases the resources used by this probe.

@api private

# File lib/ovirtsdk4/probe.rb, line 153
def close
  # Close the HTTP client:
  @client.close if @client
end
probe() click to toggle source

Probes the server to detect the supported versions of the API.

@return [Array<ProbeResult>] An array of objects of the OvirtSDK4::ProbeResult class.

@api private

# File lib/ovirtsdk4/probe.rb, line 142
def probe
  path = detect_path
  raise Error, 'API path not found' unless path
  detect_version(path).map { |version| ProbeResult.new(version: version) }
end

Private Instance Methods

detect_path() click to toggle source
# File lib/ovirtsdk4/probe.rb, line 199
def detect_path
  PATH_CANDIDATES.each do |path|
    begin
      response = send(path: path)
      return path if response.code == 200
      raise Error, 'Unauthorized' if response.code == 401
    end
  end
  nil
end
detect_v3(path) click to toggle source
# File lib/ovirtsdk4/probe.rb, line 217
def detect_v3(path)
  response = send(version: '3', path: path)
  special_response_regexp_in_api3 =~ response.body
end
detect_v4(path) click to toggle source
# File lib/ovirtsdk4/probe.rb, line 222
def detect_v4(path)
  response = send(version: '4', path: path)
  special_response_regexp_in_api4 =~ response.body
end
detect_version(path) click to toggle source
# File lib/ovirtsdk4/probe.rb, line 210
def detect_version(path)
  versions = []
  versions << '3' if detect_v3(path)
  versions << '4' if detect_v4(path)
  versions
end
send(opts = {}) click to toggle source
# File lib/ovirtsdk4/probe.rb, line 168
def send(opts = {})
  # Get the options and assign default values:
  path = opts[:path] || ''
  version = opts[:version] || '4'

  # Create empty request and response objects:
  request = HttpRequest.new
  response = HttpResponse.new

  # Set the URL:
  request.url = "https://#{@host}:#{@port}#{path}"

  # Set the headers:
  request.headers.merge!(
    'User-Agent'   => "RubyProbe/#{VERSION}",
    'Version'      => version,
    'Content-Type' => 'application/xml',
    'Accept'       => 'application/xml'
  )

  # Set authentication:
  request.username = @username
  request.password = @password

  # Send the request and wait for the response:
  @client.send(request, response)

  # Return the response object:
  response
end
special_response_regexp_in_api3() click to toggle source

The methods below are based on headers oVirt returns depending on the API version it supports when queried with <version: 3> or <version: 4> header. Refer to spec to see the return values.

# File lib/ovirtsdk4/probe.rb, line 230
def special_response_regexp_in_api3
  /major=/
end
special_response_regexp_in_api4() click to toggle source
# File lib/ovirtsdk4/probe.rb, line 234
def special_response_regexp_in_api4
  /<major>/
end