libvirt_ffi 0.4.0 → 0.5.3

data/lib/libvirt/util.rb

@@ -2,23 +2,36 @@
 
 module Libvirt
   module Util
-    class << self
+    UNIT_TO_BYTES = {
+        b: 1,
+        bytes: 1,
+        KB: 1_000,
+        KiB: 1_024,
+        k: 1_024,
+        MB: 1_000_000,
+        M: 1_048_576,
+        MiB: 1_048_576,
+        GB: 1_000_000_000,
+        G: 1_073_741_824,
+        GiB: 1_073_741_824,
+        TB: 1_000_000_000_000,
+        T: 1_099_511_627_776,
+        TiB: 1_099_511_627_776
+    }.freeze
 
-      def logger=(logger)
-        @logger = logger
-      end
+    class << self
+      attr_writer :logger
 
-      def logger
-        @logger
-      end
+      attr_reader :logger
 
       def log(severity, prog = nil, &block)
         return if @logger.nil?
+
         @logger.public_send(severity, prog, &block)
       end
 
       def library_path
-        %w(libvirt libvirt.so.0)
+        %w[libvirt libvirt.so.0]
       end
 
       # @param [Integer] version_number ulong
@@ -36,13 +49,53 @@ module Libvirt
       def parse_enum(enum, value)
         if value.is_a?(Symbol)
           raise ArgumentError, 'invalid enum value' unless enum.symbols.include?(value)
+
           return [enum.find(value), value]
         end
 
         raise ArgumentError, 'invalid enum value' unless enum.symbol_map.values.include?(value)
+
         [value, enum.symbol_map[value]]
       end
 
+      # Bitwise OR integer flags calculation for C language.
+      # @param flags [Integer,Symbol,Array<Symbol>,Hash{Symbol=>Boolean},nil]
+      # @param enum [FFI::Enum]
+      # @param default [Integer] optional (default 0x0)
+      # @return [Integer] bitwise OR of keys
+      #  @example Usage:
+      #    parse_flags(nil, enum)
+      #    parse_flags({MANAGED_SAVE: true, SNAPSHOTS_METADATA: true, NVRAM: false}, enum)
+      #    parse_flags({managed_save: true, snapshots_metadata: true, keep_nvram: nil}, enum)
+      #    parse_flags(3, enum)
+      #    parse_flags([:MANAGED_SAVE, :SNAPSHOTS_METADATA], enum)
+      #    parse_flags([:managed_save, :snapshots_metadata], enum)
+      #
+      def parse_flags(flags, enum, default: 0x0)
+        flags = default if flags.nil?
+        flags = enum[flags] if flags.is_a?(Symbol)
+        return flags if flags.is_a?(Integer)
+
+        result = 0x0
+        flags = flags.select { |_, v| v }.keys if flags.is_a?(Hash)
+
+        raise ArgumentError, 'flags must be an Integer or a Hash or an Array' unless flags.is_a?(Array)
+
+        flags.each do |key|
+          result |= enum[key.to_s.upcase.to_sym]
+        end
+
+        result
+      end
+
+      # @param value [Integer,String]
+      # @param unit [String,Symbol] default 'bytes'
+      # @return [Integer] memory in bytes
+      def parse_memory(value, unit)
+        unit ||= 'bytes'
+        multiplier = UNIT_TO_BYTES.fetch(unit.to_sym)
+        Integer(value) * multiplier
+      end
     end
   end
 end

data/lib/libvirt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Libvirt
-  VERSION = '0.4.0'
+  VERSION = '0.5.3'
 end

data/lib/libvirt/xml.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'libvirt/util'
+
+module Libvirt
+  module Xml
+    # https://libvirt.org/format.html
+    # namespace for libvirt xml objects.
+    # does not loaded by default.
+    # requires nokogiri.
+
+    require 'libvirt/xml/generic'
+    require 'libvirt/xml/storage_pool'
+    require 'libvirt/xml/storage_volume'
+    require 'libvirt/xml/memory'
+    require 'libvirt/xml/graphics'
+    require 'libvirt/xml/disk'
+    require 'libvirt/xml/max_vcpu'
+    require 'libvirt/xml/vcpu'
+    require 'libvirt/xml/domain'
+  end
+end

data/lib/libvirt/xml/disk.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Libvirt
+  module Xml
+    class Disk < Generic
+      # https://libvirt.org/formatdomain.html#elementsDisks
+
+      attribute :type, type: :attr
+      attribute :device, type: :attr
+      attribute :model, type: :attr
+      attribute :raw_io, type: :attr, name: :rawio, cast: :bool
+      attribute :sg_io, type: :attr, name: :sgio
+      attribute :snapshot, type: :attr
+      attribute :source_file, name: :file, path: './source', type: :attr
+      attribute :source_dev, name: :dev, path: './source', type: :attr
+      attribute :source_dir, name: :dir, path: './source', type: :attr
+      attribute :source_protocol, name: :protocol, path: './source', type: :attr
+      attribute :source_pool, name: :pool, path: './source', type: :attr
+      attribute :source_volume, name: :volume, path: './source', type: :attr
+      attribute :source_mode, name: :mode, path: './source', type: :attr
+      attribute :source_name, name: :name, path: './source', type: :attr
+      attribute :source_type, name: :type, path: './source', type: :attr
+      attribute :source_managed, name: :managed, path: './source', type: :attr, cast: :bool
+      attribute :source_namespace, name: :namespace, path: './source', type: :attr
+      attribute :source_index, name: :index, path: './source', type: :attr
+      attribute :source_host_name, name: :name, path: './source/host', type: :attr
+      attribute :source_host_port, name: :port, path: './source/host', type: :attr
+      attribute :source_host_transport, name: :transport, path: './source/host', type: :attr
+      attribute :source_host_socket, name: :socket, path: './source/host', type: :attr
+      attribute :source_snapshot_name, name: :name, path: './source/snapshot', type: :attr
+      attribute :source_config_file, name: :file, path: './source/config', type: :attr
+      # TODO: source/auth
+      # TODO: source/encryption
+      # TODO: source/reservations
+      # TODO: source/initiator
+      # TODO: source/address
+      # TODO: source/slices
+      # TODO: backingStore
+      # TODO: mirror
+      # TODO: target
+      # TODO: iotune
+      # TODO: driver
+      # TODO: backenddomain
+      # TODO: boot
+      # TODO: encryption
+      # TODO: readonly
+      # TODO: shareable
+      # TODO: transient
+      # TODO: serial
+      # TODO: wwn
+      # TODO: vendor
+      # TODO: product
+      # TODO: address
+      # TODO: auth
+      # TODO: geometry
+      # TODO: blockio
+    end
+  end
+end

data/lib/libvirt/xml/domain.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Libvirt
+  module Xml
+    class Domain < Generic
+      # https://libvirt.org/formatdomain.html
+
+      root_path './domain'
+
+      attribute :name
+      attribute :uuid
+      attribute :gen_id, path: './genid'
+      attribute :title
+      attribute :description
+      attribute :metadata, type: :raw
+      attribute :vcpu, type: :struct, class: MaxVcpu
+      attribute :vcpus, type: :struct, array: true, class: Vcpu, cast: ->(objects, _) { objects.sort_by(&:id) }
+      attribute :memory, type: :struct, class: Memory
+      attribute :current_memory, type: :struct, class: Memory
+      attribute :max_memory, type: :struct, class: Memory
+      attribute :resource_partitions, path: './resource/partition', array: true
+      attribute :on_power_off
+      attribute :on_reboot
+      attribute :on_crash
+      attribute :on_lock_failure
+      attribute :device_graphics, type: :struct, path: './devices/graphics', class: Graphics, array: true
+      attribute :device_disks, type: :struct, path: './devices/disk', class: Disk, array: true
+      # https://libvirt.org/formatdomain.html#elementsDevices
+      # todo devices/emulator
+      # todo devices/interface
+      # todo devices/filesystem
+      # todo devices/controller
+      # todo devices/lease
+      # todo devices/hostdev
+      # todo devices/redirdev
+      # todo devices/smartcard
+      # todo devices/input
+      # todo devices/hub
+      # todo devices/video
+      # todo devices/parallel
+      # todo devices/serial
+      # todo devices/console
+      # todo devices/channel
+      # todo devices/sound
+      # todo devices/watchdog
+      # todo devices/memballoon
+      # todo devices/rng
+      # todo devices/tpm
+      # todo devices/nvram
+      # todo devices/panic
+      # todo devices/shmem
+      # todo devices/memory
+      # todo devices/iommu
+      # todo devices/vsock
+      # todo os
+      # todo bootloader
+      # todo bootloader_args
+      # todo sysinfo
+      # todo iothreads
+      # todo iothreadids
+      # todo cputune
+      # todo memoryBacking
+      # todo memtune
+      # todo numatune
+      # todo blkiotune
+      # todo cpu
+      # todo pm
+      # todo features
+      # todo clock
+      # todo perf
+      # todo seclabel
+      # todo keywrap
+      # todo launchSecurity
+    end
+  end
+end

data/lib/libvirt/xml/generic.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Libvirt
+  module Xml
+    class Generic
+      class_attribute :_root_path, instance_writer: false, default: '.'
+      class_attribute :_attributes_opts, instance_writer: false, default: {}
+
+      def self.inherited(subclass)
+        subclass._root_path = '.'
+        subclass._attributes_opts = _attributes_opts.dup
+      end
+
+      def self.root_path(path)
+        self._root_path = path
+      end
+
+      def self.attributes(*names)
+        options = names.extract_options!
+        names.each do |name|
+          _attributes_opts.merge!(name.to_sym => options.dup)
+        end
+        attr_accessor(*names)
+      end
+
+      def self.attribute(name, options = {})
+        _attributes_opts.merge!(name.to_sym => options.dup)
+        attr_accessor name
+      end
+
+      # @param xml [String]
+      # @return [Class<LibvirtXml::Generic>]
+      def self.load(xml)
+        xml_node = Nokogiri::XML(xml).xpath(_root_path).first
+        new(xml_node)
+      end
+
+      # Build xml object with attributes.
+      # @param attrs [Hash]
+      # @return [Xml::Base]
+      def self.build(attrs = {})
+        xml_node = Nokogiri::XML(nil)
+        obj = new(xml_node)
+        attrs.each { |key, val| obj.public_send("#{key}=", val) }
+        obj
+      end
+
+      # @param xml_node [Nokogiri::XML::Element]
+      def initialize(xml_node)
+        @xml_node = xml_node
+        parse_xml_node
+      end
+
+      # @param attr [Symbol,String]
+      # @return [Object,nil]
+      def [](attr)
+        read_attribute(attr)
+      end
+
+      # @param attr [Symbol,String]
+      # @param value [Object,nil]
+      # @return [Object,nil]
+      def []=(attr, value)
+        write_attribute(attr, value)
+      end
+
+      # @return [Hash{Symbol=>(Object,nil)}]
+      def to_h
+        _attributes_opts.map do |name, _opts|
+          value = public_send(name)
+          [name, serialize_for_hash(value)]
+        end.to_h
+      end
+
+      # @return [String]
+      def to_xml
+        @xml_node.to_xml
+      end
+
+      delegate :as_json, :to_json, to: :to_h
+
+      private
+
+      def parse_xml_node
+        _attributes_opts.each do |name, opts|
+          value = parse_node(name, opts)
+          value = decode(value, opts)
+          write_attribute name, value
+        end
+      end
+
+      # Parse node value using "parse_node_#{type}" method.
+      # @param name [Symbol]
+      # @param opts [Hash{Symbol=>Object}]
+      # @return [Object, nil]
+      def parse_node(name, opts)
+        type = opts[:type] || :text
+        meth = "parse_node_#{type}"
+
+        if opts[:apply]
+          opts[:apply].call(@xml_node, opts)
+        elsif respond_to?(meth, true)
+          send(meth, name, opts)
+        else
+          raise ArgumentError, "Invalid :type option #{type.inspect} for attribute #{name}"
+        end
+      end
+
+      # Cast value using "decode_#{type}" method.
+      # @param value [String]
+      # @param opts [Hash{Symbol=>Object}]
+      # @return [Object, nil]
+      def decode(value, opts)
+        return if value.nil?
+
+        cast = opts[:cast]
+        return value if cast.nil?
+
+        meth = "decode_#{cast}"
+
+        if opts[:array]
+          value.map do |val|
+            if cast.is_a?(Proc)
+              cast.call(val, opts)
+            elsif respond_to?(meth, true)
+              send(meth, val, opts)
+            else
+              raise ArgumentError, "invalid :cast option #{cast.inspect}"
+            end
+          end
+        end
+
+        if cast.is_a?(Proc)
+          cast.call(value, opts)
+        elsif respond_to?(meth, true)
+          send(meth, value, opts)
+        else
+          raise ArgumentError, "invalid :cast option #{cast.inspect}"
+        end
+      end
+
+      # @param value [String, Boolean]
+      # @return [Boolean]
+      def decode_bool(value, _opts)
+        return value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+        return true if value == 'yes'
+
+        return false if value == 'no'
+
+        nil
+      end
+
+      # @param value [String, Integer]
+      # @return [Integer]
+      # @raise [ArgumentError]
+      def decode_int(value, _opts)
+        Integer(value)
+      end
+
+      def find_nodes(name, opts)
+        value_name = opts[:name]&.to_sym || name
+        path = opts[:path] || "./#{value_name}"
+        path == :root ? [@xml_node] : @xml_node.xpath(path)
+      end
+
+      def parse_node_text(name, opts)
+        nodes = find_nodes(name, opts)
+
+        return nodes.map(&:text) if opts[:array]
+
+        node = nodes.first
+        return if node.nil?
+
+        node.text
+      end
+
+      def parse_node_attr(name, opts)
+        nodes = find_nodes name, { path: :root }.merge(opts)
+        value_name = opts[:name]&.to_sym || name
+
+        return nodes.map { |node| node[value_name.to_s] } if opts[:array]
+
+        node = nodes.first
+        return if node.nil?
+
+        node[value_name.to_s]
+      end
+
+      def parse_node_struct(name, opts)
+        klass = opts[:class]
+        raise ArgumentError, "Invalid :class option nil for attribute #{name}" if klass.nil?
+
+        nodes = find_nodes(name, opts)
+
+        return nodes.map { |node| klass.new(node) } if opts[:array]
+
+        node = nodes.first
+        return if node.nil?
+
+        klass.new(node)
+      end
+
+      def parse_node_raw(name, opts)
+        nodes = find_nodes(name, opts)
+
+        return nodes.map(&:to_xml) if opts[:array]
+
+        node = nodes.first
+        return if node.nil?
+
+        node.to_xml
+      end
+
+      def parse_node_memory(name, opts)
+        nodes = find_nodes(name, opts)
+
+        if opts[:array]
+          return [] if nodes.empty?
+
+          return nodes.map { |node| Util.parse_memory node.text, node['unit'] }
+        end
+
+        node = nodes.first
+        return if node.nil?
+
+        Util.parse_memory node.text, node['unit']
+      end
+
+      def read_attribute(attr)
+        attr = attr.to_sym
+        raise ArgumentError, "can't find attribute #{attr}" unless _attributes_opts.key?(attr)
+
+        instance_variable_get :"@#{attr}"
+      end
+
+      def write_attribute(attr, value)
+        attr = attr.to_sym
+        raise ArgumentError, "can't find attribute #{attr}" unless _attributes_opts.key?(attr)
+
+        instance_variable_set :"@#{attr}", value
+      end
+
+      def serialize_for_hash(value)
+        return value.to_h if value.is_a?(Generic)
+        return value.map { |val| serialize_for_hash(val) } if value.is_a?(Array)
+
+        value
+      end
+    end
+  end
+end