vagrant-xapi 0.0.1 → 1.0.0

data/lib/vagrant-xapi/api/client.rb

@@ -0,0 +1,393 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+require_relative "errors"
+require_relative "redactor"
+require_relative "transport"
+require_relative "task"
+require_relative "http_transfer"
+require_relative "../version"
+
+module VagrantPlugins
+  module Xapi
+    module Api
+      # XAPI client over JSON-RPC 2.0 (https://<host>/jsonrpc) using only the
+      # Ruby standard library.
+      #
+      #   client = Client.new(host: "xcp1", username: "root", password: "...")
+      #   client.login
+      #   vm = client.call("VM.get_by_uuid", uuid)       # session is prepended
+      #   client.VM.get_record(vm)                        # same, via proxy
+      #   client.run_task("VM.clone", vm, "name")         # Async.* + wait
+      #
+      # One Client = one session. It is safe to share between threads.
+      class Client
+        API_VERSION = "1.0"
+        ORIGINATOR = "vagrant-xapi/#{VERSION}"
+        MAX_REDIRECTS = 2
+
+        attr_reader :host, :port, :username, :features, :session_ref, :transport
+
+        def initialize(host:, username:, password:, port: 443, tls: {}, api_timeout: 60,
+                       task_timeout: 3600, logger: nil)
+          @host = host
+          @port = port
+          @username = username
+          @password = password
+          @tls = tls
+          @api_timeout = api_timeout
+          @task_timeout = task_timeout
+          @logger = SafeLogger.new(logger)
+          @transport = Transport.new(host: host, port: port, tls: tls, timeout: api_timeout)
+          @id = 0
+          @id_mutex = Mutex.new
+          @login_mutex = Mutex.new
+          @session_ref = nil
+          @features = {}
+          @host_transports = {}
+          @host_transports_mutex = Mutex.new
+          @master_ref = nil
+          Redactor.register(password)
+        end
+
+        attr_reader :task_timeout, :api_timeout
+
+        def logged_in?
+          !@session_ref.nil?
+        end
+
+        # Logs in, following HOST_IS_SLAVE to the pool master.
+        def login
+          @login_mutex.synchronize { login_unlocked unless @session_ref }
+          self
+        end
+
+        def logout
+          ref = nil
+          @login_mutex.synchronize do
+            ref = @session_ref
+            @session_ref = nil
+          end
+          return unless ref
+
+          begin
+            rpc("session.logout", [ref])
+          rescue Error => e
+            @logger.debug("logout failed: #{e.message}")
+          ensure
+            Redactor.unregister(ref)
+            @transport.shutdown
+          end
+        end
+
+        # Calls a XAPI method with the session prepended to params.
+        # Retries once after re-login on SESSION_INVALID.
+        def call(method, *params)
+          call_with_session(method, params)
+        end
+
+        # Calls a method with a longer read timeout (event.from).
+        def call_with_timeout(method, read_timeout, *params)
+          call_with_session(method, params, read_timeout: read_timeout)
+        end
+
+        # Starts Async.<method> and waits for the task.
+        # @return [Task::Result]
+        def run_task(method, *params, label: nil, timeout: nil, progress: nil, cancel: nil)
+          task_ref = call("Async.#{method}", *params)
+          wait_task(task_ref, label: label || method, timeout: timeout, progress: progress, cancel: cancel)
+        end
+
+        def wait_task(task_ref, label:, timeout: nil, progress: nil, cancel: nil)
+          Task.new(self, task_ref, label: label, logger: @logger)
+              .wait(timeout: timeout || @task_timeout, progress: progress, cancel: cancel)
+        end
+
+        # Creates a task object for HTTP handlers that accept task_id.
+        def create_task(label)
+          call("task.create", label, ORIGINATOR)
+        end
+
+        def http
+          HttpTransfer.new(self)
+        end
+
+        # Proxy: client.VM.get_record(ref) == client.call("VM.get_record", ref)
+        class ClassProxy
+          def initialize(client, klass)
+            @client = client
+            @klass = klass
+          end
+
+          def method_missing(name, *args)
+            @client.call("#{@klass}.#{name}", *args)
+          end
+
+          def respond_to_missing?(*)
+            true
+          end
+        end
+
+        # Only the capitalized classes: lowercase ones (host, pool, ...) would
+        # clash with the client's own methods. Use #call for those.
+        XAPI_CLASSES = %w[VM VBD VDI VIF SR PBD PIF VM_guest_metrics VM_metrics VTPM].freeze
+
+        XAPI_CLASSES.each do |klass|
+          define_method(klass) { ClassProxy.new(self, klass) }
+        end
+
+        # Optional XAPI features, detected on first login.
+        def feature?(name)
+          @features[name.to_sym] ? true : false
+        end
+
+        def set_feature(name, value)
+          @features = @features.merge(name.to_sym => value)
+        end
+
+        def session_cookie
+          "session_id=#{current_session}"
+        end
+
+        # The HTTP handlers answer an expired or evicted session with 401:
+        # log in again (unless another thread already did), as #call does on
+        # SESSION_INVALID. cookie is the one that was refused.
+        def renew_session(cookie)
+          relogin(cookie.to_s.delete_prefix("session_id="), nil)
+          nil
+        end
+
+        # The pool master's host ref.
+        def master_ref
+          @master_ref ||= call("pool.get_master", call("pool.get_all").first)
+        end
+
+        # Transport to a specific pool host, for HTTP transfers and the
+        # console. The master uses the main connection. For other members the
+        # certificate is fetched through the (already verified) master with
+        # host.get_server_certificate and pinned, because a configured pin or
+        # a hostname check would not match them.
+        def transport_for(host_ref)
+          return @transport if host_ref.nil? || host_ref == master_ref
+
+          address = call("host.get_address", host_ref)
+          @host_transports_mutex.synchronize do
+            @host_transports[address] ||= Transport.new(host: address, port: @port, tls: member_tls(host_ref),
+                                                        timeout: @api_timeout)
+          end
+        end
+
+        private
+
+        def member_tls(host_ref)
+          pem = call("host.get_server_certificate", host_ref)
+          { fingerprint: OpenSSL::Digest::SHA256.hexdigest(OpenSSL::X509::Certificate.new(pem).to_der) }
+        rescue XapiError, OpenSSL::X509::CertificateError => e
+          @logger.debug("no server certificate for member host (#{e.message}); using the configured TLS settings")
+          @tls
+        end
+
+        def current_session
+          login unless @session_ref
+          @session_ref || login_and_get
+        end
+
+        def login_and_get
+          @login_mutex.synchronize do
+            login_unlocked unless @session_ref
+            @session_ref
+          end
+        end
+
+        def call_with_session(method, params, read_timeout: nil)
+          ref = current_session
+          attempt = 0
+          begin
+            rpc(method, [ref, *params], read_timeout: read_timeout)
+          rescue XapiError => e
+            raise unless e.code == "SESSION_INVALID" && attempt.zero?
+
+            attempt += 1
+            @logger.info("session expired, logging in again")
+            ref = relogin(ref, e)
+            retry
+          end
+        end
+
+        def next_id
+          @id_mutex.synchronize { @id += 1 }
+        end
+
+        # Logs in into a local variable first; the session is only swapped in
+        # once it is complete, so other threads never see a half state.
+        def login_unlocked
+          redirects = 0
+          member = nil
+          begin
+            ref = rpc("session.login_with_password", [@username, @password, API_VERSION, ORIGINATOR])
+          rescue TlsError => e
+            raise unless member
+
+            # The master's address never appears in the configuration, so
+            # say where it came from.
+            raise TlsError.new(e.host, "#{e.reason}. #{redirect_hint(member, e.host)}")
+          rescue XapiError => e
+            raise unless e.code == "HOST_IS_SLAVE" && redirects < MAX_REDIRECTS && e.params.first
+
+            master = e.params.first
+            # One pin matches only the member's own certificate, never the
+            # master's. With several (the pool's hosts) the master's
+            # certificate is checked against them.
+            if Transport.normalize_fingerprints(@tls && @tls[:fingerprint]).size == 1
+              raise PoolMemberError.new(@host, master)
+            end
+
+            redirects += 1
+            member ||= @host
+            @logger.info("#{@host} is a pool member; reconnecting to master #{master}")
+            @transport.shutdown
+            @host = master
+            @transport = Transport.new(host: master, port: @port, tls: @tls, timeout: @api_timeout)
+            retry
+          end
+          Redactor.register(ref)
+          features = detect_features(ref)
+          # Answers learned during the session (ImageUpload's qcow2 probe per
+          # host) survive a relogin.
+          @features = features.merge(@features.select { |key, _| key.to_s.start_with?("qcow2_import@") })
+          @master_ref = features[:master_ref]
+          @session_ref = ref
+        end
+
+        # For a TLS failure on the master after HOST_IS_SLAVE, by TLS mode.
+        # `vagrant xapi hosts` cannot help yet: it would take the same way.
+        def redirect_hint(member, master)
+          said = "#{member} is a pool member and sent the login on to its master #{master}"
+          if Transport.normalize_fingerprints(@tls && @tls[:fingerprint]).empty?
+            "#{said}; the master's certificate must pass the same CA check, for the address #{master}"
+          else
+            "#{said}, whose certificate is not among the tls_fingerprint pins. Add the master's fingerprint " \
+              "(openssl s_client -connect #{master}:#{@port} </dev/null | openssl x509 -noout -fingerprint " \
+              "-sha256); after that `vagrant xapi hosts` lists the fingerprints of all hosts"
+          end
+        end
+
+        # Logs in again unless another thread already did. A failing login
+        # raises its own error (e.g. a rotated password), not SESSION_INVALID.
+        # @return [String] the session to use
+        def relogin(failed_ref, _error)
+          @login_mutex.synchronize do
+            return @session_ref if @session_ref && @session_ref != failed_ref
+
+            @session_ref = nil
+            Redactor.unregister(failed_ref) if failed_ref
+            login_unlocked
+            @session_ref
+          end
+        end
+
+        def detect_features(ref)
+          features = {}
+          begin
+            pool = rpc("pool.get_all", [ref]).first
+            master = rpc("pool.get_master", [ref, pool])
+            features[:master_ref] = master
+            major = rpc("host.get_API_version_major", [ref, master]).to_i
+            minor = rpc("host.get_API_version_minor", [ref, master]).to_i
+            features[:api_version] = [major, minor]
+            sw = rpc("host.get_software_version", [ref, master])
+            features[:product_brand] = sw["product_brand"] || sw["platform_name"]
+            features[:product_version] = sw["product_version"] || sw["platform_version"]
+          rescue XapiError => e
+            @logger.debug("version detection failed: #{e.message}")
+          end
+          features[:vtpm] = method_available?(ref, "VTPM.get_all")
+          features
+        end
+
+        def method_available?(ref, method)
+          rpc(method, [ref])
+          true
+        rescue XapiError => e
+          return false if %w[MESSAGE_METHOD_UNKNOWN UNKNOWN_XENAPI_MESSAGE].include?(e.code)
+
+          # Other errors (e.g. RBAC) still mean the class exists.
+          true
+        end
+
+        # Raw JSON-RPC call; params as given.
+        def rpc(method, params, read_timeout: nil)
+          id = next_id
+          body = JSON.generate(jsonrpc: "2.0", method: method, params: params, id: id)
+          @logger.debug { "xapi -> #{method} #{log_params(method, params).inspect}" }
+
+          response = @transport.with_connection(read_timeout: read_timeout) do |http|
+            req = Net::HTTP::Post.new("/jsonrpc")
+            req["Content-Type"] = "application/json"
+            req["User-Agent"] = ORIGINATOR
+            req.body = body
+            http.request(req)
+          end
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise ProtocolError, "HTTP #{response.code} from #{@host} for #{method}"
+          end
+
+          parse_response(method, response.body)
+        end
+
+        def parse_response(method, body)
+          data = begin
+            JSON.parse(body)
+          rescue JSON::ParserError => e
+            raise ProtocolError, "invalid JSON from #{@host} for #{method}: #{e.message}"
+          end
+
+          if data.is_a?(Hash) && data["error"]
+            err = data["error"]
+            code, params = extract_error(err)
+            @logger.debug("xapi <- #{method} error #{code} #{params.inspect}")
+            raise XapiError.new(code, params, method_name: method)
+          end
+          raise ProtocolError, "no result from #{@host} for #{method}" unless data.is_a?(Hash) && data.key?("result")
+
+          result = data["result"]
+          # Some XAPI versions wrap like XML-RPC: {"Status":"Success","Value":...}
+          if result.is_a?(Hash) && result.key?("Status") && result.size <= 2
+            if result["Status"] == "Success"
+              result = result["Value"]
+            else
+              info = Array(result["ErrorDescription"])
+              raise XapiError.new(info.first || "UNKNOWN", info.drop(1), method_name: method)
+            end
+          end
+          @logger.debug("xapi <- #{method} ok")
+          result
+        end
+
+        def extract_error(err)
+          if err.is_a?(Hash)
+            data = err["data"]
+            if data.is_a?(Array) && data.first.is_a?(String) && err["message"].to_s.empty?
+              [data.first, data.drop(1)]
+            else
+              [err["message"] || err["code"] || "UNKNOWN", Array(data)]
+            end
+          elsif err.is_a?(Array)
+            [err.first, err.drop(1)]
+          else
+            [err.to_s, []]
+          end
+        end
+
+        def log_params(method, params)
+          return ["[user]", Redactor::MASK, *params.drop(2)] if method.start_with?("session.login")
+
+          params.each_with_index.map { |p, i| i.zero? && p.to_s.start_with?("OpaqueRef:") ? "<session>" : p }
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-xapi/api/errors.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module VagrantPlugins
+  module Xapi
+    module Api
+      # Base class for everything the XAPI client raises. The client layer does
+      # not know Vagrant; the integration layer translates these into
+      # Vagrant::Errors::VagrantError subclasses (see VagrantPlugins::Xapi::Errors).
+      class Error < StandardError; end
+
+      # An error returned by XAPI itself, e.g. ["SR_FULL", "123", "456"].
+      class XapiError < Error
+        attr_reader :code, :params, :method_name
+
+        def initialize(code, params = [], method_name: nil)
+          @code = code.to_s
+          @params = Array(params).map(&:to_s)
+          @method_name = method_name
+          super("#{@code}#{@params.empty? ? "" : " #{@params.inspect}"}" \
+                "#{method_name ? " (#{method_name})" : ""}")
+        end
+      end
+
+      # The host could not be reached at the TCP/HTTP level.
+      class ConnectionError < Error
+        attr_reader :host, :reason
+
+        def initialize(host, reason)
+          @host = host
+          @reason = reason
+          super("cannot connect to #{host}: #{reason}")
+        end
+      end
+
+      # The host did not answer in time (connect or read timeout).
+      class TimeoutError < ConnectionError; end
+
+      # TLS verification failed (certificate, CA or fingerprint pin).
+      class TlsError < Error
+        attr_reader :host, :reason
+
+        def initialize(host, reason)
+          @host = host
+          @reason = reason
+          super("TLS verification of #{host} failed: #{reason}")
+        end
+      end
+
+      # Login on a pool member while a TLS pin is configured: the pin cannot
+      # match the master's certificate, so the redirect is refused.
+      class PoolMemberError < Error
+        attr_reader :host, :master
+
+        def initialize(host, master)
+          @host = host
+          @master = master
+          super("#{host} is a pool member; the pool master is #{master}")
+        end
+      end
+
+      # The response was not valid JSON-RPC.
+      class ProtocolError < Error; end
+
+      # HTTP transfer (/import, /export, ...) failed.
+      class HttpError < Error
+        attr_reader :status, :path
+
+        def initialize(status, path, body = nil)
+          @status = status.to_i
+          @path = path
+          detail = body.to_s.strip[0, 300]
+          super("HTTP #{status} on #{path}#{detail.empty? ? "" : ": #{detail}"}")
+        end
+      end
+
+      # A task did not finish within the configured timeout.
+      class TaskTimeout < Error
+        attr_reader :label, :timeout
+
+        def initialize(label, timeout)
+          @label = label
+          @timeout = timeout
+          super("task '#{label}' did not finish within #{timeout}s")
+        end
+      end
+
+      # A task was cancelled (by Ctrl-C or by someone else).
+      class TaskCancelled < Error
+        attr_reader :label
+
+        def initialize(label)
+          @label = label
+          super("task '#{label}' was cancelled")
+        end
+      end
+    end
+  end
+end