ovirt-engine-sdk 4.0.1 → 4.4.1

data/lib/ovirtsdk4/errors.rb

@@ -0,0 +1,70 @@
+#
+# Copyright (c) 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.
+#
+
+module OvirtSDK4
+  #
+  # The base class for all errors raised by the SDK.
+  #
+  class Error
+    #
+    # An error code associated to the error. For HTTP related errors, this will be the HTTP response code returned by
+    # the server. For example, if retrieving of a virtual machine fails because it doesn't exist this attribute will
+    # contain the integer value 404. Note that this may be `nil` if the error is not HTTP related.
+    #
+    # @return [Integer] The HTTP error code.
+    #
+    attr_accessor :code
+
+    #
+    # The `Fault` object associated to the error.
+    #
+    # @return [Fault] The fault object associated to the error, if a fault was provided by the server, `nil` otherwise.
+    #
+    attr_accessor :fault
+  end
+
+  #
+  # This class of error indicates that an authentiation or authorization problem happenend, like incorrect user name,
+  # incorrect password, or missing permissions.
+  #
+  class AuthError < Error
+  end
+
+  #
+  # This class of error indicates that the name of the server or the name of the proxy can't be resolved to an IP
+  # address, or that the connection can't be stablished because the server is down or unreachable.
+  #
+  # Note that for this class of error the `code` and `fault` attributes will always be empty, as no response from the
+  # server will be available to populate them.
+  #
+  class ConnectionError < Error
+  end
+
+  #
+  # This class of error indicates that an object can't be found.
+  #
+  class NotFoundError < Error
+  end
+
+  #
+  # This class of error indicates that an operation timed out.
+  #
+  # Note that for this class of error the `code` and `fault` attributes will always be empty, as no response from the
+  # server will be available to populate them.
+  #
+  class TimeoutError < Error
+  end
+end

data/lib/ovirtsdk4/probe.rb

@@ -0,0 +1,324 @@
+#
+# Copyright (c) 2016-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.
+#
+
+module OvirtSDK4
+  #
+  # This class is used to probe the engine to find which API versions it supports.
+  #
+  class Probe
+    #
+    # 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.
+    #
+    def self.probe(opts)
+      probe = nil
+      begin
+        probe = Probe.new(opts)
+        probe.probe
+      ensure
+        probe.close if probe
+      end
+    end
+
+    ENGINE_CERTIFICATE_PATH =
+      '/ovirt-engine/services/pki-resource?resource=engine-certificate&format=OPENSSH-PUBKEY'.freeze
+
+    #
+    # This class method receives a set of options that define the server to probe and returns a boolean value
+    # that represents whether an oVirt instance was detected.
+    #
+    # @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] :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 [Integer] :timeout (0) Set a connection timeout, in seconds. If the value is 0 no timeout is set.
+    #
+    # @return [Boolean] Boolean value, `true` if an oVirt instance was detected.
+    #
+    def self.exists?(opts)
+      probe = nil
+      begin
+        opts[:insecure] = true
+        probe = Probe.new(opts)
+        probe.exists?
+      ensure
+        probe.close if probe
+      end
+    end
+
+    #
+    # 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
+    #
+    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]
+      @timeout        = opts[:timeout]
+
+      # 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,
+        timeout:        @timeout
+      )
+    end
+
+    #
+    # 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
+    #
+    def probe
+      path = detect_path
+      raise Error, 'API path not found' unless path
+
+      detect_version(path).map { |version| ProbeResult.new(version: version) }
+    end
+
+    #
+    # Probes the server to detect if it has an ovirt instance running on it
+    #
+    # @return [Boolean] `true` if oVirt instance was detected, false otherwise
+    #
+    # @api private
+    #
+    def exists?
+      response = send(path: ENGINE_CERTIFICATE_PATH)
+      response.code == 200
+    end
+
+    #
+    # Releases the resources used by this probe.
+    #
+    # @api private
+    #
+    def close
+      # Close the HTTP client:
+      @client.close if @client
+    end
+
+    private
+
+    #
+    # We will only check these paths, as there is where the API is available in common installations of the engine.
+    #
+    PATH_CANDIDATES = [
+      '/api',
+      '/ovirt-engine/api'
+    ].freeze
+
+    def send(opts = {})
+      # Get the options and assign default values:
+      path = opts[:path] || ''
+      version = opts[:version] || '4'
+
+      # Create the request:
+      request = HttpRequest.new
+      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 = @client.wait(request)
+      raise response if response.is_a?(Exception)
+
+      response
+    end
+
+    def detect_path
+      PATH_CANDIDATES.each do |path|
+        response = send(path: path)
+        return path if response.code == 200
+        raise AuthError, 'Unauthorized' if response.code == 401
+      end
+      nil
+    end
+
+    def detect_version(path)
+      versions = []
+      versions << '3' if detect_v3(path)
+      versions << '4' if detect_v4(path)
+      versions
+    end
+
+    def detect_v3(path)
+      response = send(version: '3', path: path)
+      special_response_regexp_in_api3 =~ response.body
+    end
+
+    def detect_v4(path)
+      response = send(version: '4', path: path)
+      special_response_regexp_in_api4 =~ response.body
+    end
+
+    # 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.
+    def special_response_regexp_in_api3
+      /major=/
+    end
+
+    def special_response_regexp_in_api4
+      /<major>/
+    end
+  end
+
+  #
+  # The probe returns an array of instances of this class.
+  #
+  class ProbeResult
+    attr_reader :version
+
+    #
+    # This method is used to initialize a class instance,
+    #
+    # @param opts [Hash] The attributes of the result.
+    #
+    # @option opts [String] :version The version obtained as the result of the probe.
+    #
+    def initialize(opts)
+      @version = opts[:version]
+    end
+
+    # Override the comparison method.
+    def ==(other)
+      other.class == self.class && other.state == state
+    end
+
+    alias eql? ==
+
+    # Should always be overriden if one overrides ==, used to get a hash value
+    # for the object.
+    def hash
+      state.hash
+    end
+
+    # @api private
+    def state
+      [version]
+    end
+  end
+end

data/lib/ovirtsdk4/reader.rb

@@ -15,7 +15,6 @@
 #
 
 module OvirtSDK4
-
   #
   # This is the base class for all the XML readers used by the SDK. It contains the utility methods used by all
   # of them.
@@ -23,7 +22,6 @@ module OvirtSDK4
   # @api private
   #
   class Reader
-
     #
     # Reads a string value, assuming that the cursor is positioned at the start element that contains the value.
     #
@@ -31,7 +29,7 @@ module OvirtSDK4
     # @return [String]
     #
     def self.read_string(reader)
-      return reader.read_element
+      reader.read_element
     end
 
     #
@@ -42,7 +40,7 @@ module OvirtSDK4
     # @return [Array<String>]
     #
     def self.read_strings(reader)
-      return reader.read_elements
+      reader.read_elements
     end
 
     #
@@ -53,13 +51,14 @@ module OvirtSDK4
     #
     def self.parse_boolean(text)
       return nil if text.nil?
+
       case text.downcase
       when 'false', '0'
-        return false
+        false
       when 'true', '1'
-        return true
+        true
       else
-        raise Error.new("The text '#{text}' isn't a valid boolean value.")
+        raise Error, "The text '#{text}' isn't a valid boolean value."
       end
     end
 
@@ -70,7 +69,7 @@ module OvirtSDK4
     # @return [Boolean]
     #
     def self.read_boolean(reader)
-      return Reader.parse_boolean(reader.read_element)
+      Reader.parse_boolean(reader.read_element)
     end
 
     #
@@ -81,7 +80,7 @@ module OvirtSDK4
     # @return [Array<Boolean>]
     #
     def self.read_booleans(reader)
-      return reader.read_elements.map { |text| Reader.parse_boolean(text) }
+      reader.read_elements.map { |text| Reader.parse_boolean(text) }
     end
 
     #
@@ -92,10 +91,11 @@ module OvirtSDK4
     #
     def self.parse_integer(text)
       return nil if text.nil?
+
       begin
-        return Integer(text, 10)
-      rescue
-        raise Error.new("The text '#{text}' isn't a valid integer value.")
+        Integer(text, 10)
+      rescue ArgumentError
+        raise Error, "The text '#{text}' isn't a valid integer value."
       end
     end
 
@@ -106,7 +106,7 @@ module OvirtSDK4
     # @return [Integer]
     #
     def self.read_integer(reader)
-      return Reader.parse_integer(reader.read_element)
+      Reader.parse_integer(reader.read_element)
     end
 
     #
@@ -117,20 +117,21 @@ module OvirtSDK4
     # @return [Array<Integer>]
     #
     def self.read_integers(reader)
-      return reader.read_elements.map { |text| Reader.parse_integer(text) }
+      reader.read_elements.map { |text| Reader.parse_integer(text) }
     end
 
     #
     # Converts the given text to a decimal value.
     #
-    # @return [Fixnum]
+    # @return [Float]
     #
     def self.parse_decimal(text)
       return nil if text.nil?
+
       begin
-        return Float(text)
-      rescue
-        raise Error.new("The text '#{text}' isn't a valid decimal value.")
+        Float(text)
+      rescue ArgumentError
+        raise Error, "The text '#{text}' isn't a valid decimal value."
       end
     end
 
@@ -138,10 +139,10 @@ module OvirtSDK4
     # Reads a decimal value, assuming that the cursor is positioned at the start element that contains the value.
     #
     # @param reader [XmlReader]
-    # @return [Fixnum]
+    # @return [Float]
     #
     def self.read_decimal(reader)
-      return Reader.parse_decimal(reader.read_element)
+      Reader.parse_decimal(reader.read_element)
     end
 
     #
@@ -149,10 +150,10 @@ module OvirtSDK4
     # values.
     #
     # @param reader [XmlReader]
-    # @return [Array<Fixnum>]
+    # @return [Array<Float>]
     #
     def self.read_decimals(reader)
-      return reader.read_elements.map { |text| Reader.parse_decimal(text) }
+      reader.read_elements.map { |text| Reader.parse_decimal(text) }
     end
 
     #
@@ -163,10 +164,11 @@ module OvirtSDK4
     #
     def self.parse_date(text)
       return nil if text.nil?
+
       begin
-        return DateTime.xmlschema(text)
-      rescue
-        raise Error.new("The text '#{text}' isn't a valid date.")
+        DateTime.xmlschema(text)
+      rescue ArgumentError
+        raise Error, "The text '#{text}' isn't a valid date."
       end
     end
 
@@ -177,7 +179,7 @@ module OvirtSDK4
     # @return [DateTime]
     #
     def self.read_date(reader)
-      return Reader.parse_date(reader.read_element)
+      Reader.parse_date(reader.read_element)
     end
 
     #
@@ -188,7 +190,45 @@ module OvirtSDK4
     # @return [Array<DateTime>]
     #
     def self.read_dates(reader)
-      return reader.read_elements.map { |text| Reader.parse_date(text) }
+      reader.read_elements.map { |text| Reader.parse_date(text) }
+    end
+
+    #
+    # Converts the given text to an enum.
+    #
+    # @param enum_module [Module]
+    # @param text [String]
+    # @return [String]
+    #
+    def self.parse_enum(enum_module, text)
+      return nil unless text
+
+      values = enum_module.constants.map { |const| enum_module.const_get(const) }
+      values.detect { |value| value.casecmp(text).zero? }
+    end
+
+    #
+    # Reads a enum value, assuming that the cursor is positioned at the
+    # start element that contains the value.
+    #
+    # @param enum_module [Module]
+    # @param reader [XmlReader]
+    # @return [Array<String>]
+    #
+    def self.read_enum(enum_module, reader)
+      Reader.parse_enum(enum_module, reader.read_element)
+    end
+
+    #
+    # Reads a list of enum values, assuming that the cursor is positioned
+    # at the start element of the element that contains the first value.
+    #
+    # @param enum_module [Module]
+    # @param reader [XmlReader]
+    # @return [Array<String>]
+    #
+    def self.read_enums(enum_module, reader)
+      reader.read_elements.map { |text| Reader.parse_enum(enum_module, text) }
     end
 
     #
@@ -196,7 +236,7 @@ module OvirtSDK4
     # example, for the `vm` tag it will contain a reference to the `VmReader.read_one` method, and for the `vms` tag
     # it will contain a reference to the `VmReader.read_many` method.
     #
-    @@readers = {}
+    @readers = {}
 
     #
     # Registers a read method.
@@ -205,7 +245,7 @@ module OvirtSDK4
     # @param reader [Method] The reference to the method that reads the object corresponding to the `tag`.
     #
     def self.register(tag, reader)
-      @@readers[tag] = reader
+      @readers[tag] = reader
     end
 
     #
@@ -223,7 +263,7 @@ module OvirtSDK4
       elsif source.is_a?(XmlReader)
         cursor = source
       else
-        raise ArgumentError.new("Expected a 'String' or 'XmlReader', but got '#{source.class}'")
+        raise ArgumentError, "Expected a 'String' or 'XmlReader', but got '#{source.class}'"
       end
 
       # Do the actual read, and make sure to always close the XML reader if we created it:
@@ -233,20 +273,14 @@ module OvirtSDK4
 
         # Select the specific reader according to the tag:
         tag = cursor.node_name
-        reader = @@readers[tag]
-        if reader.nil?
-          raise Error.new("Can't find a reader for tag '#{tag}'")
-        end
+        reader = @readers[tag]
+        raise Error, "Can't find a reader for tag '#{tag}'" if reader.nil?
 
         # Read the object using the specific reader:
-        return reader.call(cursor)
+        reader.call(cursor)
       ensure
-        if !cursor.nil? && !cursor.equal?(source)
-          cursor.close
-        end
+        cursor.close if !cursor.nil? && !cursor.equal?(source)
       end
     end
-
   end
-
 end