ovirt-engine-sdk 4.0.1 → 4.4.1

data/lib/ovirtsdk4/connection.rb

@@ -0,0 +1,695 @@
+#
+# Copyright (c) 2015-2017 Red Hat, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'json'
+require 'tempfile'
+require 'uri'
+
+module OvirtSDK4
+  #
+  # 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.
+  #
+  class Connection
+    #
+    # Creates a new connection to the API server.
+    #
+    # [source,ruby]
+    # ----
+    # connection = OvirtSDK4::Connection.new(
+    #   url: 'https://engine.example.com/ovirt-engine/api',
+    #   username: 'admin@internal',
+    #   password: '...',
+    #   ca_file:'/etc/pki/ovirt-engine/ca.pem'
+    # )
+    # ----
+    #
+    # @param opts [Hash] The options used to create the connection.
+    #
+    # @option opts [String] :url A string containing the base URL of the server, usually something like
+    #   `\https://server.example.com/ovirt-engine/api`.
+    #
+    # @option opts [String] :username The name of the user, something like `admin@internal`.
+    #
+    # @option opts [String] :password The password of the user.
+    #
+    # @option opts [String] :token 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.
+    #
+    # @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 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.
+    #
+    # @option opts [Array<String>] :ca_certs 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.
+    #
+    # @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 [Logger] :log The logger where the log messages will be written.
+    #
+    # @option opts [Boolean] :kerberos (false) A boolean flag indicating if Kerberos authentication should be used
+    #   instead of user name and password to obtain the OAuth token.
+    #
+    # @option opts [Integer] :timeout (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.
+    #
+    # @option opts [Integer] :connect_timeout (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.
+    #
+    # @option opts [Boolean] :compress (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.
+    #
+    # @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.
+    #
+    # @option opts [Hash] :headers 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.
+    #
+    # @option opts [Integer] :connections (1) The maximum number of connections to open to the host. The value must
+    #   be greater than 0.
+    #
+    # @option opts [Integer] :pipeline (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.
+    #
+    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
+
+    #
+    # Returns a reference to the root of the services tree.
+    #
+    # @return [SystemService]
+    #
+    def system_service
+      @system_service ||= SystemService.new(self, '')
+    end
+
+    #
+    # 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`.
+    #
+    # @param path [String] The path of the service, for example `vms/123/diskattachments`.
+    # @return [Service]
+    # @raise [Error] If there is no service corresponding to the given path.
+    #
+    def service(path)
+      system_service.service(path)
+    end
+
+    #
+    # Sends an HTTP request, making sure that multiple threads are coordinated correctly.
+    #
+    # @param request [HttpRequest] The request object containing the details of the HTTP request to send.
+    #
+    # @api private
+    #
+    def send(request)
+      @mutex.synchronize { internal_send(request) }
+    end
+
+    #
+    # Waits for the response to the given request, making sure that multiple threads are coordinated correctly.
+    #
+    # @param request [HttpRequest] The request object whose corresponding response you want to wait for.
+    # @return [HttpResponse] A request object containing the details of the HTTP response received.
+    #
+    # @api private
+    #
+    def wait(request)
+      @mutex.synchronize { internal_wait(request) }
+    end
+
+    #
+    # 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`.
+    #
+    # @param raise_exception [Boolean]
+    #
+    # @param timeout [Integer] (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.
+    #
+    # @return [Boolean]
+    #
+    def test(raise_exception = false, timeout = nil)
+      system_service.get(timeout: timeout)
+      true
+    rescue StandardError
+      raise if raise_exception
+
+      false
+    end
+
+    #
+    # 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.
+    #
+    # @return [String]
+    #
+    def authenticate
+      # rubocop:disable Naming/MemoizedInstanceVariableName
+      @token ||= create_access_token
+      # rubocop:enable Naming/MemoizedInstanceVariableName
+    end
+
+    #
+    # Indicates if the given object is a link. An object is a link if it has an `href` attribute.
+    #
+    # @return [Boolean]
+    #
+    def link?(object)
+      !object.href.nil?
+    end
+
+    #
+    # The `link?` method used to be named `is_link?`, and we need to preserve it for backwards compatibility, but try to
+    # avoid using it.
+    #
+    # @return [Boolean]
+    #
+    # @deprecated Please use `link?` instead.
+    #
+    alias is_link? link?
+
+    #
+    # Follows the `href` attribute of the given object, retrieves the target object and returns it.
+    #
+    # @param object [Type] The object containing the `href` attribute.
+    # @raise [Error] If the `href` attribute has no value, or the link can't be followed.
+    #
+    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
+
+    #
+    # Releases the resources used by this connection, making sure that multiple threads are coordinated correctly.
+    #
+    def close
+      @mutex.synchronize { internal_close }
+    end
+
+    #
+    # Checks that the content type of the given response is JSON. If it is JSON then it does nothing. If it isn't
+    # JSON then it raises an exception.
+    #
+    # @param response [HttpResponse] The HTTP response to check.
+    #
+    # @api private
+    #
+    def check_json_content_type(response)
+      check_content_type(JSON_CONTENT_TYPE_RE, 'JSON', response)
+    end
+
+    #
+    # Checks that the content type of the given response is XML. If it is XML then it does nothing. If it isn't
+    # XML then it raises an exception.
+    #
+    # @param response [HttpResponse] The HTTP response to check.
+    #
+    # @api private
+    #
+    def check_xml_content_type(response)
+      check_content_type(XML_CONTENT_TYPE_RE, 'XML', response)
+    end
+
+    #
+    # Creates and raises an error containing the details of the given HTTP response.
+    #
+    # @param response [HttpResponse] The HTTP response where the details of the raised error will be taken from.
+    # @param detail [String, Fault] (nil) The detail of the error. It can be a string or a `Fault` object.
+    #
+    # @api private
+    #
+    def raise_error(response, detail = nil)
+      # Check if the detail is a fault:
+      fault = detail.is_a?(Fault) ? detail : nil
+
+      # Build the error message from the response and the fault:
+      message = ''
+      unless fault.nil?
+        unless fault.reason.nil?
+          message << ' ' unless message.empty?
+          message << "Fault reason is \"#{fault.reason}\"."
+        end
+        unless fault.detail.nil?
+          message << ' ' unless message.empty?
+          message << "Fault detail is \"#{fault.detail}\"."
+        end
+      end
+      unless response.nil?
+        unless response.code.nil?
+          message << ' ' unless message.empty?
+          message << "HTTP response code is #{response.code}."
+        end
+        unless response.message.nil?
+          message << ' ' unless message.empty?
+          message << "HTTP response message is \"#{response.message}\"."
+        end
+      end
+
+      # If the detail is a string, append it to the message:
+      if detail.is_a?(String)
+        message << ' ' unless message.empty?
+        message << detail
+        message << '.'
+      end
+
+      # Create and populate the error:
+      klass = Error
+      unless response.nil?
+        case response.code
+        when 401, 403
+          klass = AuthError
+        when 404
+          klass = NotFoundError
+        end
+      end
+      error = klass.new(message)
+      error.code = response.code if response
+      error.fault = fault
+
+      raise error
+    end
+
+    #
+    # Returns a string representation of the connection.
+    #
+    # @return [String] The string representation.
+    #
+    def inspect
+      "#<#{self.class.name}:#{@url}>"
+    end
+
+    #
+    # Returns a string representation of the connection.
+    #
+    # @return [String] The string representation.
+    #
+    def to_s
+      inspect
+    end
+
+    #
+    # Returns a string representation of the connection.
+    #
+    # @return [String] The string representation.
+    #
+
+    private
+
+    #
+    # Regular expression used to check JSON content type.
+    #
+    # @api private
+    #
+    JSON_CONTENT_TYPE_RE = %r{^\s*(application|text)/json\s*(;.*)?$}i.freeze
+
+    #
+    # Regular expression used to check XML content type.
+    #
+    # @api private
+    #
+    XML_CONTENT_TYPE_RE = %r{^\s*(application|text)/xml\s*(;.*)?$}i.freeze
+
+    #
+    # The typical URL path, used just to generate informative error messages.
+    #
+    # @api private
+    #
+    TYPICAL_PATH = '/ovirt-engine/api'.freeze
+
+    #
+    # Checks the content type of the given HTTP response and raises an exception if it isn't the expected one.
+    #
+    # @param expected_re [Regex] The regular expression used to check the expected content type.
+    # @param expected_name [String] The name of the expected content type.
+    # @param response [HttpResponse] The HTTP response to check.
+    #
+    # @api private
+    #
+    def check_content_type(expected_re, expected_name, response)
+      content_type = response.headers['content-type']
+      return if expected_re =~ content_type
+
+      detail = "The response content type '#{content_type}' isn't #{expected_name}"
+      url = URI(@url)
+      if url.path != TYPICAL_PATH
+        detail << ". Is the path '#{url.path}' included in the 'url' parameter correct?"
+        detail << " The typical one is '#{TYPICAL_PATH}'"
+      end
+      raise_error(response, detail)
+    end
+
+    #
+    # Obtains the access token from SSO to be used for bearer authentication.
+    #
+    # @return [String] The access token.
+    #
+    # @api private
+    #
+    def create_access_token
+      # Build the URL and parameters required for the request:
+      url, parameters = build_sso_auth_request
+
+      # Send the request and wait for the request:
+      response = get_sso_response(url, parameters)
+      response = response[0] if response.is_a?(Array)
+
+      # Check the response and raise an error if it contains an error code:
+      error = get_sso_error_message(response)
+      raise AuthError, "Error during SSO authentication: #{error}" if error
+
+      response['access_token']
+    end
+
+    #
+    # Revoke the SSO access token.
+    #
+    # @api private
+    #
+    def revoke_access_token
+      # Build the URL and parameters required for the request:
+      url, parameters = build_sso_revoke_request
+
+      # Send the request and wait for the response:
+      response = get_sso_response(url, parameters)
+      response = response[0] if response.is_a?(Array)
+
+      # Check the response and raise an error if it contains an error code:
+      error = get_sso_error_message(response)
+      raise AuthError, "Error during SSO revoke: #{error}" if error
+    end
+
+    #
+    # Execute a get request to the SSO server and return the response.
+    #
+    # @param url [String] The URL of the SSO server.
+    #
+    # @param parameters [Hash] The parameters to send to the SSO server.
+    #
+    # @return [Hash] The JSON response.
+    #
+    # @api private
+    #
+    def get_sso_response(url, parameters)
+      # Create the request:
+      request = HttpRequest.new
+      request.method = :POST
+      request.url = url
+      request.headers = {
+        'User-Agent'   => "RubySDK/#{VERSION}",
+        'Content-Type' => 'application/x-www-form-urlencoded',
+        'Accept'       => 'application/json'
+      }
+      request.body = URI.encode_www_form(parameters)
+
+      # Add the global headers:
+      request.headers.merge!(@headers) if @headers
+
+      # Send the request and wait for the response:
+      @client.send(request)
+      response = @client.wait(request)
+      raise response if response.is_a?(Exception)
+
+      # Check the returned content type:
+      check_json_content_type(response)
+
+      # Parse and return the JSON response:
+      JSON.parse(response.body)
+    end
+
+    #
+    # Builds a the URL and parameters to acquire the access token from SSO.
+    #
+    # @return [Array] An array containing two elements, the first is the URL of the SSO service and the second is a hash
+    #   containing the parameters required to perform authentication.
+    #
+    # @api private
+    #
+    def build_sso_auth_request
+      # Compute the entry point and the parameters:
+      parameters = {
+        scope: 'ovirt-app-api'
+      }
+      if @kerberos
+        entry_point = 'token-http-auth'
+        parameters[:grant_type] = 'urn:ovirt:params:oauth:grant-type:http'
+      else
+        entry_point = 'token'
+        parameters.merge!(
+          grant_type: 'password',
+          username:   @username,
+          password:   @password
+        )
+      end
+
+      # Compute the URL:
+      url = URI(@url.to_s)
+      url.path = "/ovirt-engine/sso/oauth/#{entry_point}"
+      url = url.to_s
+
+      # Return the pair containing the URL and the parameters:
+      [url, parameters]
+    end
+
+    #
+    # Builds a the URL and parameters to revoke the SSO access token
+    #
+    # @return [Array] An array containing two elements, the first is the URL of the SSO service and the second is a hash
+    #   containing the parameters required to perform the revoke.
+    #
+    # @api private
+    #
+    def build_sso_revoke_request
+      # Compute the parameters:
+      parameters = {
+        scope: '',
+        token: @token
+      }
+
+      # Compute the URL:
+      url = URI(@url.to_s)
+      url.path = '/ovirt-engine/services/sso-logout'
+      url = url.to_s
+
+      # Return the pair containing the URL and the parameters:
+      [url, parameters]
+    end
+
+    #
+    # Extrats the error message from the given SSO response.
+    #
+    # @param response [Hash] The result of parsing the JSON document returned by the SSO server.
+    # @return [String] The error message, or `nil` if there was no error.
+    #
+    def get_sso_error_message(response)
+      # OAuth uses the 'error_code' attribute for the error code, and 'error' for the error description. But OpenID uses
+      # 'error' for the error code and 'error_description' for the description. So we need to check if the
+      # 'error_description' attribute is present, and extract the code and description accordingly.
+      description = response['error_description']
+      if description.nil?
+        code = response['error_code']
+        description = response['error']
+      else
+        code = response['error']
+      end
+      "#{code}: #{description}" if code
+    end
+
+    #
+    # Sends an HTTP request.
+    #
+    # @param request [HttpRequest] The request object containing the details of the HTTP request to send.
+    #
+    # @api private
+    #
+    def internal_send(request)
+      # Add the base URL to the request:
+      request.url = request.url.nil? ? request.url = @url : "#{@url}/#{request.url}"
+
+      # Set the headers common to all requests:
+      request.headers.merge!(
+        'User-Agent'   => "RubySDK/#{VERSION}",
+        'Version'      => '4',
+        'Content-Type' => 'application/xml',
+        'Accept'       => 'application/xml'
+      )
+
+      # Older versions of the engine (before 4.1) required the 'all_content' as an HTTP header instead of a query
+      # parameter. In order to better support those older versions of the engine we need to check if this parameter is
+      # included in the request, and add the corresponding header.
+      unless request.query.nil?
+        all_content = request.query[:all_content]
+        request.headers['All-Content'] = all_content unless all_content.nil?
+      end
+
+      # Add the global headers, but without replacing the values that may already exist:
+      request.headers.merge!(@headers) { |_name, local, _global| local } if @headers
+
+      # Set the authentication token:
+      @token ||= create_access_token
+      request.token = @token
+
+      # Send the request:
+      @client.send(request)
+    end
+
+    #
+    # Waits for the response to the given request.
+    #
+    # @param request [HttpRequest] The request object whose corresponding response you want to wait for.
+    # @return [Response] A request object containing the details of the HTTP response received.
+    #
+    # @api private
+    #
+    def internal_wait(request)
+      # Wait for the response:
+      response = @client.wait(request)
+      raise response if response.is_a?(Exception)
+
+      # If the request failed because of authentication, and it wasn't a request to the SSO service, then the
+      # most likely cause is an expired SSO token. In this case we need to request a new token, and try the original
+      # request again, but only once. It if fails again, we just return the failed response.
+      if response.code == 401 && request.token
+        @token = create_access_token
+        request.token = @token
+        @client.send(request)
+        response = @client.wait(request)
+      end
+
+      response
+    end
+
+    #
+    # Releases the resources used by this connection.
+    #
+    # @api private
+    #
+    def internal_close
+      # Revoke the SSO access token:
+      revoke_access_token if @token
+
+      # Close the HTTP client:
+      @client.close if @client
+
+      # Remove the temporary file that contains the trusted CA certificates:
+      @ca_store.unlink if @ca_store
+    end
+  end
+end