Class: OvirtSDK4::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/ovirtsdk4/connection.rb

Overview

This class is responsible for managing an HTTP connection to the engine server. It is intended as the entry point for the SDK, and it provides access to the system service and, from there, to the rest of the services provided by the API.

Instance Method Summary collapse

Constructor Details

#initialize(opts = {}) ⇒ Connection

Creates a new connection to the API server.

connection = OvirtSDK4::Connection.new(
  url: 'https://engine.example.com/ovirt-engine/api',
  username: 'admin@internal',
  password: '...',
  ca_file:'/etc/pki/ovirt-engine/ca.pem'
)

Parameters:

  • opts (Hash) (defaults to: {}) —

    The options used to create the connection.

Options Hash (opts):

  • :url (String) —

    A string containing the base URL of the server, usually something like https://server.example.com/ovirt-engine/api.

  • :username (String) —

    The name of the user, something like admin@internal.

  • :password (String) —

    The password of the user.

  • :token (String) —

    The token used to authenticate. Optionally the caller can explicitly provide the token, instead of the user name and password. If the token isn’t provided then it will be automatically created.

  • :insecure (Boolean) — default: false —

    A boolean flag that indicates if the server TLS certificate and host name should be checked.

  • :ca_file (String) —

    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 neither this nor the ca_certs options are provided, then the system wide CA certificates store is used. If both options are provided, then the certificates from both options will be trusted.

  • :ca_certs (Array<String>) —

    An array of strings containing the trusted CA certificates, in PEM format. The certificate presented by the server will be verified using these CA certificates. If neither this nor the ca_file options are provided, then the system wide CA certificates store is used. If both options are provided, then the certificates from both options will be trusted.

  • :debug (Boolean) — default: 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.

  • :log (Logger) —

    The logger where the log messages will be written.

  • :kerberos (Boolean) — default: false —

    A boolean flag indicating if Kerberos authentication should be used instead of user name and password to obtain the OAuth token.

  • :timeout (Integer) — default: 0 —

    The maximun total time to wait for the response, in seconds. A value of zero (the default) means wait for ever. If the timeout expires before the response is received a TimeoutError exception will be raised.

  • :connect_timeout (Integer) — default: 300 —

    The maximun time to wait for connection establishment, in seconds. If the timeout expires before the connection is established a TimeoutError exception will be raised.

  • :compress (Boolean) — default: true —

    A boolean flag indicating if the SDK should ask the server to send compressed responses. Note that this is a hint for the server, and that it may return uncompressed data even when this parameter is set to true. Also, compression will be automatically disabled when the debug parameter is set to true, as otherwise the debug output will be compressed as well, and then it isn’t useful.

  • :proxy_url (String) —

    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.

  • :proxy_username (String) —

    The name of the user to authenticate to the proxy server.

  • :proxy_password (String) —

    The password of the user to authenticate to the proxy server.

  • :headers (Hash) —

    Custom HTTP headers to send with all requests. The keys of the hash can be strings of symbols, and they will be used as the names of the headers. The values of the hash will be used as the names of the headers. If the same header is provided here and in the headers parameter of a specific method call, then the headers parameter of the specific method call will have precedence.

  • :connections (Integer) — default: 1 —

    The maximum number of connections to open to the host. The value must be greater than 0.

  • :pipeline (Integer) — default: 0 —

    The maximum number of request to put in an HTTP pipeline without waiting for the response. If the value is 0 (the default) then pipelining is disabled.

Raises:

  • (ArgumentError) 


109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/ovirtsdk4/connection.rb', line 109

def initialize(opts = {})
  # Get the values of the parameters and assign default values:
  @url = opts[:url]
  @username = opts[:username]
  @password = opts[:password]
  @token = opts[:token]
  @insecure = opts[:insecure] || false
  @ca_file = opts[:ca_file]
  @ca_certs = opts[:ca_certs]
  @debug = opts[:debug] || false
  @log = opts[:log]
  @kerberos = opts[:kerberos] || false
  @timeout = opts[:timeout] || 0
  @connect_timeout = opts[:connect_timeout] || 0
  @compress = opts[:compress] || true
  @proxy_url = opts[:proxy_url]
  @proxy_username = opts[:proxy_username]
  @proxy_password = opts[:proxy_password]
  @headers = opts[:headers]
  @connections = opts[:connections] || 1
  @pipeline = opts[:pipeline] || 0

  # Check that the URL has been provided:
  raise ArgumentError, "The 'url' option is mandatory" unless @url

  # Automatically disable compression when debug is enabled, as otherwise the debug output generated by
  # libcurl is also compressed, and that isn't useful for debugging:
  @compress = false if @debug

  # Create a temporary file to store the CA certificates, and populate it with the contents of the 'ca_file' and
  # 'ca_certs' options. The file will be removed when the connection is closed.
  @ca_store = nil
  if @ca_file || @ca_certs
    @ca_store = Tempfile.new('ca_store')
    @ca_store.write(::File.read(@ca_file)) if @ca_file
    if @ca_certs
      @ca_certs.each do |ca_cert|
        @ca_store.write(ca_cert)
      end
    end
    @ca_store.close
  end

  # Create the mutex that will be used to prevents simultaneous access to the same HTTP client by multiple threads:
  @mutex = Mutex.new

  # Create the HTTP client:
  @client = HttpClient.new(
    insecure:        @insecure,
    ca_file:         @ca_store ? @ca_store.path : nil,
    debug:           @debug,
    log:             @log,
    timeout:         @timeout,
    connect_timeout: @connect_timeout,
    compress:        @compress,
    proxy_url:       @proxy_url,
    proxy_username:  @proxy_username,
    proxy_password:  @proxy_password,
    connections:     @connections,
    pipeline:        @pipeline
  )
end

Instance Method Details

#authenticate ⇒ String

Performs the authentication process and returns the authentication token. Usually there is no need to call this method, as authentication is performed automatically when needed. But in some situations it may be useful to perform authentication explicitly, and then use the obtained token to create other connections, using the token parameter of the constructor instead of the user name and password.

Returns:

  • (String) 


246
247
248
249
250
 
# File 'lib/ovirtsdk4/connection.rb', line 246

def authenticate
  # rubocop:disable Naming/MemoizedInstanceVariableName
  @token ||= create_access_token
  # rubocop:enable Naming/MemoizedInstanceVariableName
end

#close ⇒ Object

Releases the resources used by this connection, making sure that multiple threads are coordinated correctly.



303
304
305
 
# File 'lib/ovirtsdk4/connection.rb', line 303

def close
  @mutex.synchronize { internal_close }
end

#follow_link(object) ⇒ Object

Follows the href attribute of the given object, retrieves the target object and returns it.

Parameters:

  • object (Type) —

    The object containing the href attribute.

Raises:

  • (Error) —

    If the href attribute has no value, or the link can’t be followed.



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'lib/ovirtsdk4/connection.rb', line 277

def follow_link(object)
  # Check that the "href" has a value, as it is needed in order to retrieve the representation of the object:
  href = object.href
  raise Error, "Can't follow link because the 'href' attribute doesn't have a value" if href.nil?

  # Check that the value of the "href" attribute is compatible with the base URL of the connection:
  prefix = URI(@url).path
  prefix += '/' unless prefix.end_with?('/')
  unless href.start_with?(prefix)
    raise Error, "The URL '#{href}' isn't compatible with the base URL of the connection"
  end

  # Remove the prefix from the URL, follow the path to the relevant service and invoke the "get" or "list" method
  # to retrieve its representation:
  path = href[prefix.length..-1]
  service = service(path)
  if object.is_a?(Array)
    service.list
  else
    service.get
  end
end

#inspect ⇒ String

Returns a string representation of the connection.

Returns:

  • (String) —

    The string representation.



395
396
397
 
# File 'lib/ovirtsdk4/connection.rb', line 395

def inspect
  "#<#{self.class.name}:#{@url}>"
end

#link?(object) ⇒ Boolean Also known as: is_link?

Indicates if the given object is a link. An object is a link if it has an href attribute.

Returns:

  • (Boolean) 


257
258
259
 
# File 'lib/ovirtsdk4/connection.rb', line 257

def link?(object)
  !object.href.nil?
end

#service(path) ⇒ Service

Returns a reference to the service corresponding to the given path. For example, if the path parameter is vms/123/diskattachments then it will return a reference to the service that manages the disk attachments for the virtual machine with identifier 123.

Parameters:

  • path (String) —

    The path of the service, for example vms/123/diskattachments.

Returns:

Raises:

  • (Error) —

    If there is no service corresponding to the given path.



190
191
192
 
# File 'lib/ovirtsdk4/connection.rb', line 190

def service(path)
  system_service.service(path)
end

#system_service ⇒ SystemService

Returns a reference to the root of the services tree.

Returns:



177
178
179
 
# File 'lib/ovirtsdk4/connection.rb', line 177

def system_service
  @system_service ||= SystemService.new(self, '')
end

#test(raise_exception = false, timeout = nil) ⇒ Boolean

Tests the connectivity with the server. If connectivity works correctly it returns true. If there is any connectivity problem it will either return false or raise an exception if the raise_exception parameter is true.

Parameters:

  • raise_exception (Boolean) (defaults to: false)
  • timeout (Integer) (defaults to: nil) —

    (nil) The maximun total time to wait for the test to complete, in seconds. If the value is nil (the default) then the timeout set globally for the connection will be used.

Returns:

  • (Boolean) 


229
230
231
232
233
234
235
236
 
# File 'lib/ovirtsdk4/connection.rb', line 229

def test(raise_exception = false, timeout = nil)
  system_service.get(timeout: timeout)
  true
rescue StandardError
  raise if raise_exception

  false
end

#to_s ⇒ String

Returns a string representation of the connection.

Returns:

  • (String) —

    The string representation.



404
405
406
 
# File 'lib/ovirtsdk4/connection.rb', line 404

def to_s
  inspect
end