vagrant-xapi 0.0.1 → 1.0.0

data/lib/vagrant-xapi/services/lock.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+
+require_relative "base"
+
+module VagrantPlugins
+  module Xapi
+    module Services
+      # A lock that works across processes, users and machines: a key
+      # vagrant-xapi.lock.<name> in the pool's other_config.
+      #
+      # pool.add_to_other_config refuses an existing key with
+      # MAP_DUPLICATE_KEY, so taking the lock is atomic. The value holds the
+      # owner and an expiry time. While the lock is held, a heartbeat keeps
+      # it alive (keys <lock>.alive.0 and .alive.1, written in turn so one of
+      # them is always fresh). Only a lock whose expiry and heartbeats have
+      # all passed counts as abandoned and may be taken over. Times are the
+      # pool master's clock, so machines with skewed clocks agree.
+      class Lock
+        KEY_PREFIX = "#{Marking::PREFIX}lock."
+
+        attr_reader :name, :owner
+
+        # @param ttl [Integer] seconds before the lock counts as abandoned
+        # @param wait [Integer] seconds to wait for a busy lock
+        def initialize(ctx, name, ttl:, wait:, poll: 2, clock: nil)
+          @ctx = ctx
+          @client = ctx.client
+          @name = name
+          @ttl = ttl
+          @wait = wait
+          @poll = poll
+          @clock = clock || method(:server_now)
+          @owner = "#{Marking.user}@#{Marking.client_host}:#{Process.pid}:#{SecureRandom.hex(4)}"
+          @held = false
+          @in_process = self.class.in_process_mutex(name)
+        end
+
+        def key
+          "#{KEY_PREFIX}#{@name}"
+        end
+
+        def held?
+          @held
+        end
+
+        # Runs the block while holding the lock.
+        def synchronize
+          # Threads of one process first serialize on a local mutex, so they
+          # do not poll XAPI against each other. Waiting for it obeys the same
+          # deadline and Ctrl-C as waiting for the pool lock.
+          deadline = @clock.call + @wait
+          announced = false
+          until @in_process.try_lock
+            raise Error.new(:lock_timeout, name: @name, holder: "another machine of this run") if @clock.call > deadline
+            raise Api::TaskCancelled, "lock #{@name}" if @ctx.cancelled?
+
+            unless announced
+              @ctx.ui&.info(:waiting_for_lock, name: @name, holder: "another machine of this run")
+              announced = true
+            end
+            sleep [@poll, 0.5].min
+          end
+          begin
+            acquire(deadline)
+            heartbeat = start_heartbeat
+            begin
+              yield
+            ensure
+              stop_heartbeat(heartbeat)
+              release
+            end
+          ensure
+            @in_process.unlock
+          end
+        end
+
+        # Refreshes one heartbeat key; called every ttl/4 while held. While we
+        # hold the lock, any other value in the slot is stale (a crashed
+        # holder's), so it is replaced.
+        # @return [Boolean] whether the heartbeat was written
+        def beat(slot)
+          slot_key = alive_key(slot)
+          remove(slot_key) if raw_value(slot_key)
+          return true if add(slot_key, new_value)
+
+          @ctx.logger&.warn("lock #{@name}: heartbeat #{slot_key} could not be written")
+          false
+        end
+
+        def acquire(deadline = nil)
+          deadline ||= @clock.call + @wait
+          announced = false
+          loop do
+            return true if try_acquire
+
+            raise Error.new(:lock_timeout, name: @name, holder: holder_description) if @clock.call > deadline
+            raise Api::TaskCancelled, "lock #{@name}" if @ctx.cancelled?
+
+            unless announced
+              @ctx.ui&.info(:waiting_for_lock, name: @name, holder: holder_description)
+              announced = true
+            end
+            sleep @poll
+          end
+        end
+
+        def try_acquire
+          return verify_held if add(key, new_value)
+
+          stale = raw_value
+          take_over(stale) if stale && abandoned?(stale)
+          @held
+        end
+
+        def release
+          return unless @held
+
+          [alive_key(0), alive_key(1)].each do |slot_key|
+            current = raw_value(slot_key)
+            remove(slot_key) if current && parse(current)["owner"] == @owner
+          end
+          current = read
+          remove(key) if current.nil? || current["owner"] == @owner
+          @held = false
+        rescue Api::Error
+          @held = false
+        end
+
+        private
+
+        def alive_key(slot)
+          "#{key}.alive.#{slot}"
+        end
+
+        def start_heartbeat
+          interval = [@ttl / 4.0, 1].max
+          @stop_beating = false
+          Thread.new do
+            slot = 0
+            until @stop_beating
+              waited = 0.0
+              while waited < interval && !@stop_beating
+                sleep 0.2
+                waited += 0.2
+              end
+              break if @stop_beating
+
+              begin
+                beat(slot)
+              rescue StandardError => e
+                @ctx.logger&.warn("lock heartbeat for #{@name} failed: #{e.message}")
+              end
+              slot = 1 - slot
+            end
+          end
+        end
+
+        # Stops the heartbeat and waits for it, so no beat lands after release.
+        def stop_heartbeat(thread)
+          return unless thread
+
+          @stop_beating = true
+          thread.join(30) || thread.kill
+        end
+
+        # A lock is abandoned when its own expiry and every heartbeat of the
+        # same owner have passed.
+        def abandoned?(stale)
+          lock = parse(stale)
+          return false unless lock.fetch("expires", 0).to_i < @clock.call
+
+          [alive_key(0), alive_key(1)].none? do |slot_key|
+            beat = raw_value(slot_key)
+            next false unless beat
+
+            value = parse(beat)
+            value["owner"] == lock["owner"] && value.fetch("expires", 0).to_i >= @clock.call
+          end
+        end
+
+        # Seconds since the epoch on the pool master; the local clock when
+        # the master's time cannot be read.
+        def server_now
+          @server_offset ||= begin
+            raw = @client.call("host.get_servertime", @client.call("pool.get_master", pool))
+            Time.strptime(raw.to_s, "%Y%m%dT%H:%M:%S%z").to_i - Time.now.to_i
+          rescue Api::Error, ArgumentError => e
+            @ctx.logger&.warn("lock #{@name}: cannot read the pool master's time (#{e.message}); " \
+                              "using this machine's clock, so clock skew between machines matters")
+            0
+          end
+          Time.now.to_i + @server_offset
+        end
+
+        def new_value
+          JSON.generate("owner" => @owner, "expires" => @clock.call + @ttl)
+        end
+
+        # Taking over an abandoned lock is serialized through a second key,
+        # also set atomically: XAPI has no compare-and-swap, so without it two
+        # processes could both remove the stale value and each think they
+        # hold the lock.
+        def take_over(stale)
+          guard = "#{key}.takeover"
+          guard_value = JSON.generate("owner" => @owner, "expires" => @clock.call + 60)
+          unless add(guard, guard_value)
+            # A guard left by a crashed taker: remove it, but only if it is
+            # still that same value (not a fresh guard of another process).
+            current_guard = raw_value(guard)
+            remove(guard) if current_guard && expired?(current_guard) && raw_value(guard) == current_guard
+            return
+          end
+
+          begin
+            # Still the same stale value? Then nobody else took it over.
+            return unless raw_value == stale && abandoned?(stale)
+
+            remove(key)
+            return unless add(key, new_value) && verify_held
+
+            # The crashed holder's heartbeats would block ours.
+            [alive_key(0), alive_key(1)].each { |slot_key| remove(slot_key) }
+          ensure
+            remove(guard)
+          end
+        end
+
+        # Re-read after taking the lock: only a lock that carries our owner
+        # counts as held.
+        def verify_held
+          current = read
+          @held = current ? current["owner"] == @owner : false
+        end
+
+        # @return [Boolean] whether the key was added
+        def add(name, value)
+          @client.call("pool.add_to_other_config", pool, name, value)
+          true
+        rescue Api::XapiError => e
+          raise Error.new(:lock_permission_denied, name: @name) if e.code == "RBAC_PERMISSION_DENIED"
+          raise unless e.code == "MAP_DUPLICATE_KEY"
+
+          false
+        end
+
+        def expired?(raw)
+          parse(raw).fetch("expires", 0).to_i < @clock.call
+        end
+
+        def holder_description
+          current = read
+          current ? current["owner"].to_s.sub(/:[0-9a-f]{8}\z/, "") : "unknown"
+        end
+
+        def read
+          raw = raw_value
+          raw && parse(raw)
+        end
+
+        def raw_value(name = key)
+          @client.call("pool.get_other_config", pool)[name]
+        end
+
+        def parse(raw)
+          JSON.parse(raw)
+        rescue JSON::ParserError
+          { "owner" => "unknown", "expires" => 0 }
+        end
+
+        def remove(name)
+          @client.call("pool.remove_from_other_config", pool, name)
+        rescue Api::XapiError
+          nil
+        end
+
+        def pool
+          @pool ||= @client.call("pool.get_all").first
+        end
+
+        MUTEXES = {} # rubocop:disable Style/MutableConstant
+        MUTEXES_LOCK = Mutex.new
+
+        def self.in_process_mutex(name)
+          MUTEXES_LOCK.synchronize { MUTEXES[name] ||= Mutex.new }
+        end
+      end
+    end
+  end
+end

data/lib/vagrant-xapi/services/lookup.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module VagrantPlugins
+  module Xapi
+    module Services
+      # Finds pool objects by name or UUID and turns "not found" into
+      # readable errors.
+      class Lookup
+        UUID_RE = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i.freeze
+
+        def initialize(ctx)
+          @ctx = ctx
+          @client = ctx.client
+        end
+
+        def self.uuid?(value)
+          UUID_RE.match?(value.to_s)
+        end
+
+        # @return [String, nil] VM ref, nil when the UUID is unknown
+        def vm_by_uuid(uuid)
+          return nil if uuid.nil? || uuid.to_s.empty?
+
+          @client.call("VM.get_by_uuid", uuid.to_s)
+        rescue Api::XapiError => e
+          return nil if %w[UUID_INVALID HANDLE_INVALID].include?(e.code)
+
+          raise
+        end
+
+        def pool
+          @pool ||= @client.call("pool.get_all").first
+        end
+
+        def master
+          @master ||= @client.call("pool.get_master", pool)
+        end
+
+        # @param name [String, nil] name or UUID; nil = pool default SR
+        def sr(name)
+          if name.nil? || name.to_s.empty?
+            ref = @client.call("pool.get_default_SR", pool)
+            raise Error.new(:no_default_sr) if Helpers.null_ref?(ref)
+
+            return ref
+          end
+          find(:SR, name) || raise(Error.new(:sr_not_found, name: name))
+        end
+
+        # By UUID, name, or bridge (e.g. "xenbr1"), in that order: users of the
+        # old plugin know their networks by bridge name.
+        def network(name)
+          find(:network, name) || find_by_bridge(name) || raise(Error.new(:network_not_found, name: name))
+        end
+
+        def network_by_bridge(bridge)
+          find_by_bridge(bridge) || raise(Error.new(:network_not_found, name: bridge))
+        end
+
+        # @return [String, nil] network ref
+        def find_by_bridge(bridge)
+          @client.call("network.get_all_records_where", %(field "bridge"="#{Helpers.where_value(bridge)}")).keys.first
+        rescue Api::XapiError
+          @client.call("network.get_all_records").find { |_r, n| n["bridge"] == bridge.to_s }&.first
+        end
+
+        def host(name)
+          find(:host, name, by: %w[name_label hostname address]) ||
+            raise(Error.new(:host_not_found, name: name))
+        end
+
+        # The network of the master's management PIF.
+        def management_network
+          pifs = @client.call("host.get_PIFs", master)
+          pifs.each do |pif|
+            rec = @client.call("PIF.get_record", pif)
+            return rec["network"] if rec["management"]
+          end
+          raise Error.new(:no_management_network)
+        end
+
+        # The host-internal management network (HIMN), if present.
+        def himn_network
+          @client.call("network.get_all_records").each do |ref, rec|
+            oc = rec["other_config"] || {}
+            return ref if oc["is_host_internal_management_network"].to_s == "true"
+          end
+          raise Error.new(:himn_not_found)
+        end
+
+        def other_install_media_template
+          refs = @client.call("VM.get_by_name_label", "Other install media")
+          ref = refs.find { |r| @client.call("VM.get_is_a_template", r) }
+          raise Error.new(:base_template_missing, name: "Other install media") unless ref
+
+          ref
+        end
+
+        def iso_vdi(name)
+          if Lookup.uuid?(name)
+            begin
+              return @client.call("VDI.get_by_uuid", name)
+            rescue Api::XapiError
+              nil
+            end
+          end
+          refs = @client.call("VDI.get_by_name_label", name)
+          refs.each do |ref|
+            sr = @client.call("VDI.get_SR", ref)
+            return ref if @client.call("SR.get_content_type", sr) == "iso"
+          end
+          raise Error.new(:iso_not_found, name: name)
+        end
+
+        # The host to send an HTTP transfer for this SR to: XAPI redirects
+        # (302) to a host that has the SR attached, and a streamed PUT cannot
+        # follow that. nil means the master (shared SRs, or the master has it).
+        def transfer_host_for_sr(sr)
+          hosts = attached_hosts(sr)
+          return nil if hosts.empty? || hosts.include?(master)
+
+          hosts.first
+        end
+
+        # The host for exporting a VM: one that sees all its disks' SRs,
+        # preferring the master, then the host the VM runs on.
+        def transfer_host_for_vm(vm)
+          srs = @client.call("VM.get_VBDs", vm).filter_map do |vbd|
+            rec = @client.call("VBD.get_record", vbd)
+            next if rec["type"] != "Disk" || Helpers.null_ref?(rec["VDI"])
+
+            @client.call("VDI.get_SR", rec["VDI"])
+          end.uniq
+          return nil if srs.empty?
+
+          candidates = srs.map { |sr| attached_hosts(sr) }.reject(&:empty?).reduce { |a, b| a & b } || []
+          return nil if candidates.empty? || candidates.include?(master)
+
+          resident = @client.call("VM.get_resident_on", vm)
+          candidates.include?(resident) ? resident : candidates.first
+        end
+
+        private
+
+        def find(klass, name, by: %w[name_label])
+          value = name.to_s
+          if Lookup.uuid?(value)
+            begin
+              return @client.call("#{klass}.get_by_uuid", value)
+            rescue Api::XapiError => e
+              raise unless %w[UUID_INVALID HANDLE_INVALID].include?(e.code)
+            end
+          end
+
+          if by == %w[name_label]
+            refs = @client.call("#{klass}.get_by_name_label", value)
+            raise Error.new(:ambiguous_name, kind: klass.to_s, name: value, count: refs.size) if refs.size > 1
+
+            return refs.first
+          end
+
+          matches = @client.call("#{klass}.get_all_records").select do |_ref, rec|
+            by.any? { |field| rec[field].to_s == value }
+          end
+          raise Error.new(:ambiguous_name, kind: klass.to_s, name: value, count: matches.size) if matches.size > 1
+
+          matches.keys.first
+        end
+
+        def attached_hosts(sr)
+          @client.call("SR.get_PBDs", sr).filter_map do |pbd|
+            rec = @client.call("PBD.get_record", pbd)
+            rec["host"] if rec["currently_attached"]
+          end.uniq
+        end
+      end
+    end
+  end
+end