libvirt 0.1.0 → 0.2.0

data/lib/libvirt/spec/domain.rb

@@ -1,14 +1,14 @@
+require 'libvirt/spec/domain/clock'
+require 'libvirt/spec/domain/memtune'
 require 'libvirt/spec/domain/os_booting'
 
 module Libvirt
   module Spec
     # A specification of a domain. This translates directly down to XML
     # which can be used to define and launch domains on a node by libvirt.
-    #
-    # **Note:** This class may only be temporary, and the functionality
-    # may be merged back into {Domain}. Also, the interface will likely
-    # change.
     class Domain
+      include Util
+
       attr_accessor :hypervisor
       attr_accessor :name
       attr_accessor :uuid
@@ -16,17 +16,72 @@ module Libvirt
       attr_accessor :os
       attr_accessor :memory
       attr_accessor :current_memory
+      attr_accessor :memory_backing
+      attr_accessor :memtune
       attr_accessor :vcpu
+      attr_accessor :features
 
       attr_accessor :on_poweroff
       attr_accessor :on_reboot
       attr_accessor :on_crash
 
+      attr_accessor :clock
       attr_accessor :devices
 
-      def initialize
+      # Initializes a domain specification. If a valid XML string for a domain
+      # is given, the it will attempt to be parsed into the structure. This
+      # is still very experimental. As such, if there is something which is
+      # found which is not parseable, an {Exception::UnparseableSpec} exception
+      # will be raised. Catch this and inspect the message for more information.
+      #
+      # @param [String] xml XML spec to attempt to parse into the structure.
+      def initialize(xml=nil)
         @os = OSBooting.new
+        @memtune = Memtune.new
+        @features = []
+        @clock = Clock.new
         @devices = []
+
+        load!(xml) if xml
+      end
+
+      # Attempts to load the attributes from an XML specification. **Warning:
+      # this will overwrite any already set attributes which exist in the XML.**
+      #
+      # @param [String] xml XML spec to attempt to parse into the structure.
+      def load!(xml)
+        root = Nokogiri::XML(xml).root
+        try(root.xpath("//domain[@type]"), :preserve => true) { |result| self.hypervisor = result["type"].to_sym }
+        try(root.xpath("//domain/name")) { |result| self.name = result.text }
+        try(root.xpath("//domain/uuid")) { |result| self.uuid = result.text }
+        try(root.xpath("//domain/memory")) { |result| self.memory = result.text }
+        try(root.xpath("//domain/currentMemory")) { |result| self.current_memory = result.text }
+        try(root.xpath("//domain/vcpu")) { |result| self.vcpu = result.text }
+
+        try(root.xpath("//domain/on_poweroff")) { |result| self.on_poweroff = result.text.to_sym }
+        try(root.xpath("//domain/on_reboot")) { |result| self.on_reboot = result.text.to_sym }
+        try(root.xpath("//domain/on_crash")) { |result| self.on_crash = result.text.to_sym }
+
+        try(root.xpath("//domain/clock")) { |result| self.clock = Clock.new(result) }
+        try(root.xpath("//domain/os")) { |result| self.os = OSBooting.new(result) }
+
+        try(root.xpath("//domain/devices")) do |result|
+          self.devices = []
+
+          result.element_children.each do |device|
+            self.devices << Device.load!(device)
+          end
+        end
+
+        try(root.xpath("//domain/features")) do |result|
+          self.features = []
+
+          result.element_children.each do |feature|
+            self.features << feature.name.to_sym
+          end
+        end
+
+        raise_if_unparseables(root.xpath("//domain/*"))
       end
 
       # Returns the XML for this specification. This XML may be passed
@@ -52,11 +107,31 @@ module Libvirt
             xml.currentMemory current_memory if current_memory
             xml.vcpu vcpu if vcpu
 
+            if memory_backing == :huge_pages
+              xml.memoryBacking do
+                xml.hugepages
+              end
+            end
+
+            # Memtune handles whether or not to render itself
+            memtune.to_xml(xml)
+
+            if !features.empty?
+              xml.features do
+                features.each do |feature|
+                  xml.send(feature)
+                end
+              end
+            end
+
             # Lifecycle control
             xml.on_poweroff on_poweroff if on_poweroff
             xml.on_reboot on_reboot if on_reboot
             xml.on_crash on_crash if on_crash
 
+            # Clock
+            clock.to_xml(xml)
+
             # Devices
             if !devices.empty?
               xml.devices do

data/lib/libvirt/spec/domain/clock.rb

@@ -0,0 +1,35 @@
+module Libvirt
+  module Spec
+    class Domain
+      # Time keeping configuration for a domain.
+      class Clock
+        include Util
+
+        attr_accessor :offset
+
+        # Initializes a clock specification. This should never be called
+        # directly. Instead, use a {Libvirt::Spec::Domain} spec, which
+        # contains a clock attribute.
+        def initialize(xml=nil)
+          load!(xml) if xml
+        end
+
+        # Loads clock information from the given XML string. This shouldn't
+        # be called directly, since the domain spec automatically calls
+        # this.
+        def load!(root)
+          root = Nokogiri::XML(root).root if !root.is_a?(Nokogiri::XML::Element)
+          try(root.xpath("//clock[@offset]"), :preserve => true) { |result| self.offset = result["offset"].to_sym }
+          raise_if_unparseables(root.xpath("//clock/*"))
+        end
+
+        def to_xml(parent=Nokogiri::XML::Builder.new)
+          return if !offset
+
+          parent.clock :offset => offset
+          parent.to_xml
+        end
+      end
+    end
+  end
+end

data/lib/libvirt/spec/domain/memtune.rb

@@ -0,0 +1,29 @@
+module Libvirt
+  module Spec
+    class Domain
+      # Allows the modification of details regarding the memory tuneable
+      # parameters for this domain.
+      class Memtune
+        attr_accessor :hard_limit
+        attr_accessor :soft_limit
+        attr_accessor :swap_hard_limit
+        attr_accessor :min_guarantee
+
+        def to_xml(parent=Nokogiri::XML::Builder.new)
+          # If nothing has been modified, then don't do anything
+          return if !hard_limit && !soft_limit &&
+                    !swap_hard_limit && !min_guarantee
+
+          parent.memtune do |m|
+            m.hard_limit hard_limit if hard_limit
+            m.soft_limit soft_limit if soft_limit
+            m.swap_hard_limit swap_hard_limit if swap_hard_limit
+            m.min_guarantee min_guarantee if min_guarantee
+          end
+
+          parent.to_xml
+        end
+      end
+    end
+  end
+end

data/lib/libvirt/spec/domain/os_booting.rb

@@ -11,6 +11,8 @@ module Libvirt
       #
       # TODO: Host bootloader and direct kernel bootloader options.
       class OSBooting
+        include Util
+
         attr_accessor :type
         attr_accessor :arch
         attr_accessor :loader # Part of the BIOS bootloader
@@ -26,8 +28,13 @@ module Libvirt
         attr_accessor :initrd
         attr_accessor :cmdline
 
-        def initialize
+        # Initializes an OS booting specification. This shouldn't be
+        # called directly since the domain spec automatically loads
+        # this.
+        def initialize(xml=nil)
           @boot = []
+
+          load!(xml) if xml
         end
 
         # Enables or disables the interactive boot menu prompt on guest startup.
@@ -36,6 +43,25 @@ module Libvirt
           @bootmenu_enabled = !!value
         end
 
+        # Loads the OS booting information from the given XML string. This
+        # shouldn't be called directly, since the domain spec automatically
+        # calls this.
+        def load!(root)
+          root = Nokogiri::XML(root).root if !root.is_a?(Nokogiri::XML::Element)
+          try(root.xpath("//os/type[@arch]"), :preserve => true) { |result| self.arch = result["arch"].to_sym }
+          try(root.xpath("//os/type")) { |result| self.type = result.text.to_sym }
+
+          try(root.xpath("//os/boot"), :multi => true) do |results|
+            self.boot = []
+
+            results.each do |result|
+              self.boot << result["dev"].to_sym
+            end
+          end
+
+          raise_if_unparseables(root.xpath("//os/*"))
+        end
+
         # Convert just the OS booting section to its XML representation.
         def to_xml(parent=Nokogiri::XML::Builder.new)
           parent.os do |os|

data/lib/libvirt/spec/util.rb

@@ -0,0 +1,43 @@
+module Libvirt
+  module Spec
+    # Utility methods for the spec classes. This module is typically
+    # included for each class.
+    module Util
+      # Tries the given XML search, running the block if there are any
+      # results. This allows a concise syntax for loading data from
+      # XML which may or may not exist.
+      #
+      # **Warning:** By default, the result of the search given will
+      # be removed from the XML tree. See the options below for information
+      # on how to avoid this.
+      #
+      # An additional parameter supports options given as a hash. This
+      # allows for the following to be set:
+      #
+      #   * `multi` - If true, then all results will be returned, not just
+      #     the first one.
+      #   * `preserve` - If true, then the node will not be deleted after
+      #     yielding to the block.
+      #
+      # @param [Array] search_result
+      # @param [Hash] options Additional options, which are outlined
+      #   above.
+      def try(search_result, options=nil)
+        options ||= {}
+        return if search_result.empty?
+        search_result = search_result.first if !options[:multi]
+        yield search_result
+        search_result.remove if !options[:preserve]
+      end
+
+      # This will raise an {Exception::UnparseableSpec} exception if there
+      # are any search results given. This is meant as a helper to reduce
+      # the duplicity of this feature across specs.
+      #
+      # @param [Array] search_result
+      def raise_if_unparseables(search_result)
+        raise Exception::UnparseableSpec, search_result if !search_result.empty?
+      end
+    end
+  end
+end

data/lib/libvirt/version.rb

@@ -1,3 +1,3 @@
 module Libvirt
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/libvirt.gemspec

@@ -1,6 +1,5 @@
 # -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "libvirt/version"
+require File.expand_path("../lib/libvirt/version", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "libvirt"
@@ -9,8 +8,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Mitchell Hashimoto"]
   s.email       = ["mitchell.hashimoto@gmail.com"]
   s.homepage    = "http://rubygems.org/gems/libvirt"
-  s.summary     = "A ruby client library providing the raw interface to libvirt via FFI."
-  s.description = "A ruby client library providing the raw interface to libvirt via FFI."
+  s.summary     = "A ruby client library providing an interface to libvirt via FFI."
+  s.description = "A ruby client library providing an interface to libvirt via FFI."
 
   s.rubyforge_project = "libvirt"
 

data/test/libvirt/domain_test.rb

@@ -90,6 +90,12 @@ Protest.describe("domain") do
     assert !result.empty?
   end
 
+  should "provide the spec object for the domain" do
+    result = nil
+    assert_nothing_raised { result = @instance.spec }
+    assert result.is_a?(Libvirt::Spec::Domain)
+  end
+
   should "return result of active status" do
     @instance.start
     assert @instance.active?

data/test/libvirt/spec/device_test.rb

@@ -0,0 +1,21 @@
+require 'test_helper'
+
+Protest.describe("Domain devices") do
+  setup do
+    @klass = Libvirt::Spec::Device
+  end
+
+  should "parse from XML" do
+    @instance = @klass.load!("<disk type='file'></disk>")
+    assert @instance.is_a?(Libvirt::Spec::Device::Disk)
+    assert_equal :file, @instance.type
+  end
+
+  should "be able to get defined classes by name" do
+    assert_equal Libvirt::Spec::Device::Disk, @klass.get(:disk)
+  end
+
+  should "raise an exception if an unknown device name is given" do
+    assert_raises(NameError) { @klass.get(:foo) }
+  end
+end

data/test/libvirt/spec/devices/disk_test.rb

@@ -5,103 +5,37 @@ Protest.describe("Disk device spec") do
     @klass = Libvirt::Spec::Device::Disk
   end
 
-  context "outputting XML" do
-    setup do
-      @instance = @klass.new(:file)
+  context "initialization and parsing XML" do
+    should "parse the type" do
+      @instance = @klass.new("<disk type='file'></disk>")
+      assert_equal :file, @instance.type
     end
 
-    should "output given type for type in XML" do
-      assert_xpath @instance.type.to_s, @instance.to_xml, "//disk/@type"
+    should "parse the device attribute" do
+      @instance = @klass.new("<disk device='disk'></disk>")
+      assert_equal :disk, @instance.device
     end
 
-    context "source" do
-      should "not output source if not specified" do
-        @instance.source = nil
-        assert_not_element @instance.to_xml, "//disk/source"
-      end
-
-      should "output source attr as dev for block devices" do
-        @instance.type = :block
-        @instance.source = "foo"
-        assert_xpath @instance.source, @instance.to_xml, "//disk/source/@dev"
-      end
-
-      should "output source attr as file for other devices" do
-        @instance.type = :file
-        @instance.source = "foo"
-        assert_xpath @instance.source, @instance.to_xml, "//disk/source/@file"
-      end
-    end
-
-    context "target" do
-      should "not output target if not specified" do
-        @instance.target_dev = nil
-        assert_not_element @instance.to_xml, "//disk/target"
-      end
-
-      should "not output target if only bus is given" do
-        @instance.target_dev = nil
-        @instance.target_bus = "foo"
-        assert_not_element @instance.to_xml, "//disk/target"
-      end
-
-      should "output specified dev on target" do
-        @instance.target_dev = "foo"
-        assert_xpath @instance.target_dev, @instance.to_xml, "//disk/target/@dev"
-      end
-
-      should "output specified bus on target" do
-        @instance.target_dev = "foo"
-        @instance.target_bus = "bar"
-        assert_xpath @instance.target_bus, @instance.to_xml, "//disk/target/@bus"
-      end
+    should "parse the file from the source" do
+      @instance = @klass.new("<disk type='file'><source file='foo'/></disk>")
+      assert_equal 'foo', @instance.source
     end
 
-    context "driver" do
-      should "not output if no name is given" do
-        @instance.driver = nil
-        assert_not_element @instance.to_xml, "//disk/driver"
-      end
-
-      should "output with specified driver" do
-        @instance.driver = "foo"
-        assert_xpath @instance.driver, @instance.to_xml, "//disk/driver/@name"
-      end
-
-      should "output with specified type if given" do
-        @instance.driver = "foo"
-        @instance.driver_type = "bar"
-        assert_xpath @instance.driver_type, @instance.to_xml, "//disk/driver/@type"
-      end
-
-      should "output with specified cache if given" do
-        @instance.driver = "foo"
-        @instance.driver_cache = "bar"
-        assert_xpath @instance.driver_cache, @instance.to_xml, "//disk/driver/@cache"
-      end
+    should "parse the dev from the source" do
+      @instance = @klass.new("<disk type='file'><source dev='bar'/></disk>")
+      assert_equal 'bar', @instance.source
     end
 
-    context "shareable" do
-      should "not be sharable initially" do
-        assert_not_element @instance.to_xml, "//disk/shareable"
-      end
-
-      should "be shareable if specified" do
-        @instance.shareable = true
-        assert_element @instance.to_xml, "//disk/shareable"
-      end
+    should "parse the target" do
+      @instance = @klass.new("<disk type='file'><target bus='foo' dev='bar'/></disk>")
+      assert_equal 'foo', @instance.target_bus
+      assert_equal 'bar', @instance.target_dev
     end
 
-    context "serial" do
-      should "not have serial if not specified" do
-        @instance.serial = nil
-        assert_not_element @instance.to_xml, "//disk/serial"
-      end
-
-      should "have serial if specified" do
-        @instance.serial = "foobar"
-        assert_xpath @instance.serial, @instance.to_xml, "//disk/serial"
-      end
+    should "raise an exception if unsupported tags exist" do
+      assert_raises(Libvirt::Exception::UnparseableSpec) {
+        @klass.new("<disk><foo/></disk>")
+      }
     end
   end
 end