virtuoso 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+pkg/*
+*.gem
+.bundle
+test.rb
+.yardoc/
+doc/

data/.yardopts

@@ -0,0 +1 @@
+-m markdown

data/Gemfile

@@ -0,0 +1,20 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in virtuoso.gemspec
+gem "virtuoso", :path => "."
+
+# Use libvirt-rb straight from git, since Virtuoso dev requires
+# the latest and greatest
+gem "libvirt", :git => "git://github.com/mitchellh/libvirt-rb.git"
+
+# Gems required for testing only.
+group :development do
+  gem "protest", "~> 0.4.0"
+  gem "mocha", "~> 0.9.8"
+
+  # Not JRuby, which doesn't like bluecloth
+  platforms :ruby, :mri do
+    gem "yard", "~> 0.6.1"
+    gem "bluecloth", "~> 2.0.9"
+  end
+end

data/Gemfile.lock

@@ -0,0 +1,37 @@
+GIT
+  remote: git://github.com/mitchellh/libvirt-rb.git
+  revision: d06c4aef6e52723816b76b4e46b5f8cc985d5d8a
+  specs:
+    libvirt (0.2.1.dev)
+      ffi (~> 0.6.3)
+      nokogiri (~> 1.4.3)
+
+PATH
+  remote: .
+  specs:
+    virtuoso (0.0.1)
+      libvirt (~> 0.2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bluecloth (2.0.9)
+    ffi (0.6.3)
+      rake (>= 0.8.7)
+    mocha (0.9.10)
+      rake
+    nokogiri (1.4.4)
+    protest (0.4.2)
+    rake (0.8.7)
+    yard (0.6.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bluecloth (~> 2.0.9)
+  libvirt!
+  mocha (~> 0.9.8)
+  protest (~> 0.4.0)
+  virtuoso!
+  yard (~> 0.6.1)

data/README.md

@@ -0,0 +1,68 @@
+# Virtuoso
+
+Virtuoso is a Ruby library that provides dead simple virtual machine
+management across many hypervisors, using the powerful [libvirt](http://libvirt.org)
+library underneath. Libvirt is an extremely powerful library, and the
+focus of Virtuoso is to provide an extremely simple, common API for
+managing virtual machines at the cost of sacrificing some of libvirt's
+power.
+
+Currently supported hypervisors:
+
+  - VirtualBox
+
+Since Virtuoso is built on top of [libvirt](http://libvirt.org), it isn't
+too difficult to add support for another hypervisor. The reason a libvirt-supported
+hypervisor may not be supportd by Virtuoso at this time is most likely
+because I don't have experience using that hypervisor. Open an issue if
+you'd like to see support for another hypervisor.
+
+## Installation
+
+The library is packaged as a gem:
+
+    gem install virtuoso
+
+Additionally, you may need to install libvirt, the C-library used to
+interface with the various hypervisors. On OS X the recommended way is
+using [homebrew](http://github.com/mxcl/homebrew):
+
+    brew install libvirt
+
+If you're on linux, your package manager should contain a compatible
+version of libvirt.
+
+## Project Status and Warning
+
+**Warning:** This project is extremely _alpha_. The API will most definitely
+change multiple times in the near future and the project itself will be
+a fast moving target. This status will be updated in time as the project
+matures.
+
+## Usage
+
+Below is an example of starting a VM with VirtualBox. All drivers (for
+different hypervisors) are required to conform to the same API, so the
+usage is the same for all other hypervisors.
+
+    require 'virtuoso'
+
+    # Connect to a libvirt instance. Virtuoso instantiates the proper
+    # hypervisor.
+    hypervisor = Virtuoso.connect("vbox:///session")
+
+    # Create a new VM within the hypervisor and start it
+    vm = hypervisor.new_vm
+    vm.name = "My Virtuoso VM"
+    vm.disk_image = "/home/mitchellh/lucid.vmdk"
+    vm.save
+    vm.start
+
+    # Watch it booting...
+    sleep 5
+
+    # Stop and destroy it
+    vm.stop
+    sleep 3
+    vm.destroy
+

data/Rakefile

@@ -0,0 +1,20 @@
+require 'rubygems'
+require 'bundler'
+require 'bundler/setup'
+Bundler::GemHelper.install_tasks
+
+task :default => :test
+
+desc "Run the test suite."
+task :test do
+  $:.unshift File.expand_path("../test", __FILE__)
+  files = ENV["TEST"] ? [ENV["TEST"]] : Dir["test/**/*_test.rb"]
+  files.each { |f| load f }
+end
+
+begin
+  # Documentation task
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+end

data/lib/virtuoso.rb

@@ -0,0 +1,22 @@
+require 'libvirt'
+
+module Virtuoso
+  autoload :Error, "virtuoso/error"
+  autoload :VirtualBox, "virtuoso/virtualbox"
+
+  # Holds all the "abstract" classes for specifying and documenting
+  # the Virtuoso API.
+  module API
+    autoload :Hypervisor, "virtuoso/api/hypervisor"
+    autoload :VM, "virtuoso/api/vm"
+  end
+
+  # Connects to a hypervisor given by the URL to a libvirt instance,
+  # and returns the proper hypervisor class based on the connection.
+  def self.connect(url=nil)
+    mapping = { "VBOX" => :VirtualBox }
+    conn = Libvirt.connect(url)
+    raise Error::UnsupportedHypervisorError, "Unsupported hypervisor: #{conn.hypervisor}" if !mapping[conn.hypervisor]
+    const_get(mapping[conn.hypervisor]).const_get(:Hypervisor).new(conn)
+  end
+end

data/lib/virtuoso/api/hypervisor.rb

@@ -0,0 +1,30 @@
+module Virtuoso
+  module API
+    # Base class specifying the API for all hypervisors. Every feature in
+    # this base class must be overloaded by any hypervisors.
+    class Hypervisor
+      # The libvirt connection instance.
+      attr_reader :connection
+
+      # Initializes a hypervisor with the given libvirt connection. The
+      # connection should be established through {Virtuoso.connect}, which
+      # also chooses the correct hypervisor.
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # Returns a new {VM} instance that can be used to create a new virtual
+      # machine.
+      #
+      # @return [VM]
+      def new_vm; end
+
+      # Searches for a VM with the given ID and returns it if it finds it,
+      # and otherwise returns nil. The exact semantics of the find are up to
+      # the hypervisor but typically it searches by both name and UUID.
+      #
+      # @return [VM]
+      def find(id); end
+    end
+  end
+end

data/lib/virtuoso/api/vm.rb

@@ -0,0 +1,90 @@
+module Virtuoso
+  module API
+    # Base class specifying the API that all VMs within a hypervisor must
+    # conform to.
+    class VM
+      # The libvirt connection instance.
+      attr_reader :connection
+
+      # The libvirt domain object.
+      attr_reader :domain
+
+      # The name of the VM.
+      attr_accessor :name
+
+      # The memory for the VM.
+      attr_accessor :memory
+
+      # The disk image to use as the main boot drive.
+      attr_accessor :disk_image
+
+      # Initializes a VM with the given libvirt connection.
+      def initialize(connection, domain=nil)
+        @connection = connection
+        @domain = domain
+
+        # Set reasonable defaults for fields if we can
+        @name = "My Virtuoso VM"
+        @memory = 524288 # 512 MB
+
+        # Load in the proper data
+        reload if domain
+      end
+
+      # Returns the current state of the VM. This is expected to always
+      # return the current, up-to-date state (therefore it is _not_ cached
+      # and updated only on {#reload}). The state is meant to be returned
+      # as a symbol.
+      #
+      # @return [Symbol]
+      def state; end
+
+      # Saves the VM. If the VM is new, this is expected to create it
+      # initially, otherwise this is expected to update the existing
+      # VM.
+      def save; end
+
+      # Destroys the VM, deleting any information about it. This will not
+      # destroy any disk images, nor will it stop the VM if it is running.
+      def destroy; end
+
+      # Starts the VM.
+      def start; end
+
+      # Stops the VM.
+      def stop; end
+
+      # Reloads information from about a VM which exists. Since Virtuoso
+      # can't enforce any sort of VM locking, it is possible a VM changes
+      # in the background by some other process while it is being modified.
+      # In that case, when you attempt to save, your changes will either
+      # overwrite the previous settings, or fail altogether (if someone else
+      # destroyed the VM, for example). It is up to the developer to be
+      # knowledgeable about his or her environment and account for this
+      # accordingly. If you know that a VM changed, or you're just being
+      # careful, {#reload} may be called to reload the data associated
+      # with this VM and bring it up to date.
+      def reload; end
+
+      protected
+
+      # A helper method for subclasses to mark methods which require an
+      # existing VM to function (these are methods like `start` and `stop`).
+      # This method will raise an {Error::NewVMError} if an existing VM
+      # is not set.
+      def requires_existing_vm
+        raise Error::NewVMError if !domain
+      end
+
+      # A helper method for subclasses to set a domain object to represent
+      # this VM. This properly sets up the object and reloads it for the
+      # most up to date information.
+      def set_domain(domain)
+        @domain = domain
+        @domain_spec = nil
+
+        reload if domain
+      end
+    end
+  end
+end

data/lib/virtuoso/error.rb

@@ -0,0 +1,9 @@
+module Virtuoso
+  # Any exceptions which are thrown by Virtuoso (not lower-level libraries)
+  # exist in this module.
+  module Error
+    class VirtuosoError < StandardError; end
+    class UnsupportedHypervisorError < StandardError; end
+    class NewVMError < VirtuosoError; end
+  end
+end

data/lib/virtuoso/version.rb

@@ -0,0 +1,3 @@
+module Virtuoso
+  VERSION = "0.0.1"
+end

data/lib/virtuoso/virtualbox.rb

@@ -0,0 +1,6 @@
+module Virtuoso
+  module VirtualBox
+    autoload :Hypervisor, "virtuoso/virtualbox/hypervisor"
+    autoload :VM, "virtuoso/virtualbox/vm"
+  end
+end

data/lib/virtuoso/virtualbox/hypervisor.rb

@@ -0,0 +1,21 @@
+module Virtuoso
+  module VirtualBox
+    # VirtualBox driver, allowing the control and management of
+    # VirtualBox virtual machines.
+    class Hypervisor < API::Hypervisor
+      def new_vm
+        VM.new(connection)
+      end
+
+      # Searches for a VM by name or UUID.
+      #
+      # @param [String] id Name or UUID
+      # @return [VM]
+      def find(id)
+        result = connection.domains.find(id)
+        return nil if !result
+        VM.new(connection, result)
+      end
+    end
+  end
+end

data/lib/virtuoso/virtualbox/vm.rb

@@ -0,0 +1,85 @@
+module Virtuoso
+  module VirtualBox
+    # VirtualBox VM.
+    class VM < API::VM
+      def state
+        domain ? domain.state : :new
+      end
+
+      def save
+        # Setup the basic settings for the VM
+        d = Libvirt::Spec::Domain.new
+        d.hypervisor = :vbox
+        d.name = name
+        d.memory = memory
+        d.vcpu = 1
+        d.features = [:acpi, :pae]
+        d.clock.offset = :localtime
+        d.os.type = :hvm
+        d.os.arch = :i386
+        d.os.boot = [:cdrom, :hd]
+
+        # Attach the main hard disk
+        disk = Libvirt::Spec::Device.get(:disk).new
+        disk.type = :file
+        disk.device = :disk
+        disk.source = disk_image
+        disk.target_dev = :hda
+        disk.target_bus = :ide
+        d.devices << disk
+
+        # Attach a basic NAT network interface
+        nat = Libvirt::Spec::Device.get(:interface).new
+        nat.type = :user
+        nat.mac_address = "08:00:27:8f:7a:9f"
+        nat.model_type = "82540EM"
+        d.devices << nat
+
+        # Attach video information
+        video = Libvirt::Spec::Device.get(:video).new
+        model = Libvirt::Spec::Device::VideoModel.new
+        model.type = :vbox
+        model.vram = 12
+        model.heads = 1
+        model.accel3d = false
+        model.accel2d = false
+        video.models << model
+        d.devices << video
+
+        # At this point, assuming the virtuoso settings are correct, we
+        # should have a bootable VM spec, so define it and reload the VM
+        # information.
+        @domain = connection.domains.define(d)
+        reload
+      end
+
+      def destroy
+        requires_existing_vm
+        @domain.undefine
+        @domain = nil
+      end
+
+      def start
+        requires_existing_vm
+        domain.start
+      end
+
+      def stop
+        requires_existing_vm
+        domain.stop
+      end
+
+      def reload
+        # Load the main disk image path. We assume this is the first "disk"
+        # device, though this assumption is probably pretty weak.
+        spec = domain.spec
+        disk = spec.devices.find { |d| d.is_a?(Libvirt::Spec::Device::Disk) }
+        self.disk_image = disk.source
+
+        # Load the basic attributes
+        self.name = spec.name
+        self.memory = spec.memory
+      end
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,30 @@
+require "test/unit/assertions"
+require "protest"
+require "mocha"
+require "virtuoso"
+
+class Protest::TestCase
+  include Test::Unit::Assertions
+  include Mocha::API
+
+  # Get Mocha integrated properly into the tests
+  alias :original_run :run
+  def run(report)
+    original_run(report)
+    mocha_verify
+  ensure
+    mocha_teardown
+  end
+
+  # Returns a connection to a libvirt test hypervisor.
+  def test_connection
+    Libvirt.connect("test:///default")
+  end
+
+  # Returns a domain object from the libvirt test hypervisor.
+  def test_domain
+    test_connection.domains.first
+  end
+end
+
+Protest.report_with(:progress)

data/test/virtuoso/api/vm_test.rb

@@ -0,0 +1,70 @@
+require "test_helper"
+
+Protest.describe("API::VM") do
+  setup do
+    @klass = Virtuoso::API::VM
+  end
+
+  context "requiring an existing VM" do
+    setup do
+      @impl = Class.new(@klass) do
+        def save
+          @domain = true
+        end
+
+        def start
+          requires_existing_vm
+        end
+      end
+
+      @instance = @impl.new(test_connection)
+    end
+
+    should "raise an exception if an existing VM is not set" do
+      assert_raises(Virtuoso::Error::NewVMError) { @instance.start }
+    end
+
+    should "not raise an exception if an existing VM is set" do
+      assert_nothing_raised {
+        @instance.save
+        @instance.start
+      }
+    end
+  end
+
+  context "initializing a VM" do
+    context "reloading" do
+      setup do
+        @impl = Class.new(@klass) do
+          def reload
+            throw :reloaded, :reload
+          end
+        end
+      end
+
+      should "reload if a domain is given" do
+        result = catch :reloaded do
+          @impl.new(test_connection, test_domain)
+          nil
+        end
+
+        assert_equal :reload, result
+      end
+
+      should "not load if a domain is not given" do
+        result = catch :reloaded do
+          @impl.new(test_connection)
+          nil
+        end
+
+        assert !result
+      end
+    end
+  end
+
+  context "with a VM object" do
+    setup do
+      @instance = @klass.new(test_connection)
+    end
+  end
+end

data/test/virtuoso/virtuoso_test.rb

@@ -0,0 +1,18 @@
+require "test_helper"
+
+Protest.describe("Virtuoso") do
+  setup do
+    @klass = Virtuoso
+  end
+
+  context "connecting" do
+    should "raise an exception if an unsupported hypervisor is connected to" do
+      assert_raises(Virtuoso::Error::UnsupportedHypervisorError) {
+        @klass.connect("test:///default")
+      }
+    end
+
+    # TODO: To test other connections, hypervisor must be present... so we
+    # can't guarantee and test that yet.
+  end
+end

data/virtuoso.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "virtuoso/version"
+
+Gem::Specification.new do |s|
+  s.name        = "virtuoso"
+  s.version     = Virtuoso::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Mitchell Hashimoto"]
+  s.email       = ["mitchell.hashimoto@gmail.com"]
+  s.homepage    = "http://rubygems.org/gems/virtuoso"
+  s.summary     = "Dead simple virtual machine management for many hypervisors."
+  s.description = "Dead simple virtual machine management for many hypervisors."
+
+  s.rubyforge_project = "virtuoso"
+
+  s.add_dependency "libvirt", "~> 0.2"
+
+  s.add_development_dependency "protest", "~> 0.4.0"
+  s.add_development_dependency "mocha", "~> 0.9.8"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification 
+name: virtuoso
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Mitchell Hashimoto
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-07 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: libvirt
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 2
+        version: "0.2"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: protest
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 4
+        - 0
+        version: 0.4.0
+  type: :development
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 9
+        - 8
+        version: 0.9.8
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+description: Dead simple virtual machine management for many hypervisors.
+email: 
+- mitchell.hashimoto@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .yardopts
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- lib/virtuoso.rb
+- lib/virtuoso/api/hypervisor.rb
+- lib/virtuoso/api/vm.rb
+- lib/virtuoso/error.rb
+- lib/virtuoso/version.rb
+- lib/virtuoso/virtualbox.rb
+- lib/virtuoso/virtualbox/hypervisor.rb
+- lib/virtuoso/virtualbox/vm.rb
+- test/test_helper.rb
+- test/virtuoso/api/vm_test.rb
+- test/virtuoso/virtuoso_test.rb
+- virtuoso.gemspec
+has_rdoc: true
+homepage: http://rubygems.org/gems/virtuoso
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -4389485739309843364
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -4389485739309843364
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: virtuoso
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Dead simple virtual machine management for many hypervisors.
+test_files: 
+- test/test_helper.rb
+- test/virtuoso/api/vm_test.rb
+- test/virtuoso/virtuoso_test.rb