virtuozzo 0.5.1

data/CHANGELOG.rdoc

@@ -0,0 +1,86 @@
+= CHANGELOG
+
+== 0.5.0 "Jill" 2008-11-13
+
+* Expanded documentation for Virtuozzo::SOAP::Connection class.
+* Expanded documentation for Virtuozzo::SOAP::HeaderHandler class.
+* Implemented YARD for documentation via tasks/yard.rake
+* Refactored Virtuozzo::SOAP::HeaderHandler into separate file.
+
+== 0.4.0 "Jack" 2008-11-13
+
+* Refactored drivers to use concise naming (i.e. Session instead of 
+  SessionDriver)
+* HeaderHandler now support all relevant attributes and elements for outbound
+  messages.
+
+== 0.3.0 "Tiny Tim" 2008-11-12
+
+* Refactored the driver types into the Virtuozzo::SOAP::Types module.
+
+== 0.2.0 "Little John" 2008-11-12
+
+* Refactored the mapping registries used by all the drivers into a single 
+  module under Virtuozzo::SOAP::MappingRegistries with individual modules for 
+  each driver.
+
+== 0.1.1 "Big Boy Busted" 2008-11-12
+
+* Fixed a bunch of errors in the generate code from wsdl2ruby and resolved 
+  some oddness in the Connection#initialize methods implementation.
+* Basic operations work!
+
+== 0.1.0 "Big Boy" 2008-11-12
+
+* After finding a bug in the way Virtuozzo handles parsing of SOAP headers
+  it makes SOAP the more viable option for quick implementation. Conducting 
+  major refactoring to implement SOAP API.
+* And, holy smoke, we renamed the project. The new project name is 
+  +virtuozzo+. The reasons is because it clarifies what this is an 
+  implementation of and for.
+* Supports VZLsessionm interface via SessionDriver.
+* Supports VZAenvnm interface via EnvironmentDriver.
+* Supports VZApackagem interface via TemplateDriver.
+* Supports VZArelocator interface via RelocatorDriver.
+* Supports VZAdevm interface via DeviceDriver.
+* Supports VZAnetworkm interface via NetworkDriver.
+* Supports VZAproc_info interface via ProcessInfoDriver.
+* Supports VZAup2date interface via Up2dateDriver.
+* Supports VZAsupport interface via SupportDriver.
+
+== 0.0.4 "System Overload" 2008-11-06
+
+* Implemented everything from the system target along with its necessary
+  complex types. Few things are documented as "No plans to implement" and
+  the system target stuff to handle subscribing and unsubscribing to alerts
+  is being put off.
+
+== 0.0.3 "Bastard Grandson of Timmy" 2008-11-05
+
+* Implemented ROXML for complex types and messages.
+* Dropping the idea that this library should implement a client itself.
+* Dropping method based interface for now, implementations will need to
+  explicitly craft their own messages.
+* system/login call and response is implemented.
+* vzaenvm/get_list call and response is implemented.
+* Complex type env_statusType implemented as EnvStatus.
+* Complex type tokenType implemented as Token.
+
+== 0.0.2 "Son of Timmy" 2008-10-29
+
+* Stripped all the SOAP interface code out. (Even handcrafting the packets was
+  horribly broken. Besides, SOAP sucks anyways.)
+* Refactored all the calls into methods instead of classes. This should make
+  things a little simpler. All the methods return instances of RequestMessage
+  so there shouldn't be much change for the actual socket client 
+  implementation.
+
+== 0.0.1 "Timmy" 2008-10-28
+
+* Basic methods implemented for XML API interaction in 
+  VZAgent::XML::Connection.
+* Basic methods implemented for SOAP API interaction in 
+  VZAgent::SOAP::Connection.
+* Login message classes implemented for +system+ and +sessionm+ targets.
+* Generic RequestMessage class implemented.
+* Basic constants and errors defined.

data/Manifest

@@ -0,0 +1,42 @@
+CHANGELOG.rdoc
+lib/virtuozzo/constants.rb
+lib/virtuozzo/soap/drivers/device.rb
+lib/virtuozzo/soap/drivers/environment.rb
+lib/virtuozzo/soap/drivers/network.rb
+lib/virtuozzo/soap/drivers/process.rb
+lib/virtuozzo/soap/drivers/process_info.rb
+lib/virtuozzo/soap/drivers/relocator.rb
+lib/virtuozzo/soap/drivers/session.rb
+lib/virtuozzo/soap/drivers/support.rb
+lib/virtuozzo/soap/drivers/template.rb
+lib/virtuozzo/soap/drivers/up2date.rb
+lib/virtuozzo/soap/header_handler.rb
+lib/virtuozzo/soap/mapping_registries/device.rb
+lib/virtuozzo/soap/mapping_registries/environment.rb
+lib/virtuozzo/soap/mapping_registries/network.rb
+lib/virtuozzo/soap/mapping_registries/process.rb
+lib/virtuozzo/soap/mapping_registries/process_info.rb
+lib/virtuozzo/soap/mapping_registries/relocator.rb
+lib/virtuozzo/soap/mapping_registries/session.rb
+lib/virtuozzo/soap/mapping_registries/support.rb
+lib/virtuozzo/soap/mapping_registries/template.rb
+lib/virtuozzo/soap/mapping_registries/up2date.rb
+lib/virtuozzo/soap/types/device.rb
+lib/virtuozzo/soap/types/environment.rb
+lib/virtuozzo/soap/types/network.rb
+lib/virtuozzo/soap/types/process.rb
+lib/virtuozzo/soap/types/process_info.rb
+lib/virtuozzo/soap/types/relocator.rb
+lib/virtuozzo/soap/types/session.rb
+lib/virtuozzo/soap/types/support.rb
+lib/virtuozzo/soap/types/template.rb
+lib/virtuozzo/soap/types/up2date.rb
+lib/virtuozzo/soap.rb
+lib/virtuozzo.rb
+Manifest
+Rakefile
+README.rdoc
+script/console
+script/github-gem-test
+tasks/yard.rake
+virtuozzo.gemspec

data/README.rdoc

@@ -0,0 +1,52 @@
+= +virtuozzo+
+    by James Thompson
+    http://github.com/plainprograms/virtuozzo
+
+== DESCRIPTION
+
++virtuozzo+ is designed to support working with Parallels Virtuozzo Agent's 
+XML and SOAP API from Ruby.
+
+== REQUIREMENTS
+
+* soap4r
+
+== INSTALL
+
+  $ gem sources -a http://gems.github.com/
+  $ gem install plainprograms-virtuozzo
+
+== SOURCE
+
+The +virtuozzo+ git repo is available on GitHub, which can be browsed at:
+
+  http://github.com/plainprograms/virtuozzo
+
+and cloned from:
+
+  git://github.com/plainprograms/virtuozzo.git
+
+== LICENSE
+
+(The MIT License)
+
+Copyright (c) 2008 James Thompson <james@plainprograms.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,20 @@
+require 'rubygems'
+require 'echoe'
+require 'spec/rake/spectask'
+
+Echoe.new('virtuozzo', '0.5.1') do |p|
+  p.description               = "Ruby library for Parallels Virtuozzo Agent's API"
+  p.url                       = "http://github.com/plainprograms/virtuozzo"
+  p.author                    = "James Thompson"
+  p.email                     = "james@plainprograms.com"
+  p.project                   = "virtuozzo"
+  p.need_gem                  = true
+  p.need_tar_gz               = true
+  p.need_tgz                  = true
+  p.need_zip                  = true
+  p.ignore_pattern            = ["tmp/*, script/*"]
+  p.development_dependencies  = ["echoe"]
+  p.runtime_dependencies      = ["soap4r >=1.5.8"]
+end
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/lib/virtuozzo.rb

@@ -0,0 +1,18 @@
+# = virtuozzo
+#
+# +virtuozzo+ is intended to provide an interface to the Parallels Virtuozzo
+# Agent XML & SOAP API via the Ruby programming language.
+#
+require 'base64'
+require 'rubygems'
+
+gem 'soap4r'
+
+__DIR__ = File.dirname(__FILE__)
+
+$LOAD_PATH.unshift __DIR__ unless
+  $LOAD_PATH.include?(__DIR__) ||
+  $LOAD_PATH.include?(File.expand_path(__DIR__))
+
+require 'virtuozzo/constants'
+require 'virtuozzo/soap'

data/lib/virtuozzo/constants.rb

@@ -0,0 +1,7 @@
+module Virtuozzo # :nodoc:
+  # Virtuozzo Agent's protocol version
+  PROTOCOL_VERSION = '4.0.0'
+
+  # Virtuozzo Agent's default system realm
+  DEFAULT_REALM = '00000000-0000-0000-0000-000000000000'
+end

data/lib/virtuozzo/soap.rb

@@ -0,0 +1,220 @@
+require 'virtuozzo/soap/drivers/session'
+require 'virtuozzo/soap/drivers/environment'
+require 'virtuozzo/soap/drivers/template'
+require 'virtuozzo/soap/drivers/relocator'
+require 'virtuozzo/soap/drivers/device'
+require 'virtuozzo/soap/drivers/network'
+require 'virtuozzo/soap/drivers/process_info'
+require 'virtuozzo/soap/drivers/process'
+require 'virtuozzo/soap/drivers/up2date'
+require 'virtuozzo/soap/drivers/support'
+
+require 'virtuozzo/soap/header_handler'
+
+module Virtuozzo  # :nodoc:
+  module SOAP     # :nodoc:
+    ##
+    # The Connection class provides for establishing of a SOAP session with a
+    # Virtuozzo Agent using either an SSL-secured or unsecure HTTP connection.
+    # Session data is stored for each Connection instance allowing all messages
+    # sent to be properly authenticated according to the Virtuozzo SOAP API
+    # specifications.
+    #
+    class Connection
+      ##
+      # Establish a new session with the specified host using the supplied
+      # credentials and options.
+      #
+      # The +opts+ hash may define +:debug+ to be either +true+, +false+ or the
+      # 'device' to be used for wiredumps, defaults to +false+. If set to
+      # +true+ +STDERR+ will be used for wiredumps.
+      #
+      # The +opts+ hash may define +:verify_ssl+ to be either +true+ or +false+
+      # in regards to whether SSL certificates should be verified for the
+      # various SOAP::RPC::Driver connections. The default is +false+, causing
+      # no SSL certificate verification.
+      #
+      # The +opts+ hash may define a +:realm+ for authentication. The default
+      # is the Virtuozzo system realm represented by the
+      # Virtuozzo::DEFAULT_REALM constant.
+      #
+      # @param [String] host the host to connect to
+      # @param [String] username the user to authenticate as
+      # @param [String] password the password to use for authentication
+      # @param [Hash] opts additional options for the connection
+      #
+      def initialize(host, username, password, opts = {})
+        options = {
+          :debug => false,
+          :verify_ssl => false,
+          :realm => Virtuozzo::DEFAULT_REALM
+        }.merge(opts)
+
+        @endpoint = host
+        @username = username
+        @password = password
+        @realm    = options[:realm]
+        
+        @session_id = nil
+
+        disable_ssl_verification unless options[:verify_ssl]
+        setup_debug_mode(options[:debug]) if options[:debug]
+        establish_session
+        setup_header_handler
+      end
+
+      ##
+      # Handle for the +sessionm+ interface of the Virtuozzo API.
+      #
+      # @return [SOAP::RPC::Driver] +sessionm+ SOAP::RPC::Driver instance.
+      def session
+        @session ||= Virtuozzo::SOAP::Drivers::Session.new(@endpoint)
+      end
+  
+      ##
+      # Handle for the +vzaenvm+ interface of the Virtuozzo API.
+      #
+      # @return [SOAP::RPC::Driver] +vzaenvmm+ SOAP::RPC::Driver instance.
+      def environment
+        @environment ||= Virtuozzo::SOAP::Drivers::Environment.new(@endpoint)
+      end
+  
+      ##
+      # Handle for the +vzapackagem+ interface of the Virtuozzo API.
+      #
+      # @return [SOAP::RPC::Driver] +vzapackagem+ SOAP::RPC::Driver instance.
+      def template
+        @template ||= Virtuozzo::SOAP::Drivers::Template.new(@endpoint)
+      end
+  
+      ##
+      # Handle for the +vzarelocator+ interface of the Virtuozzo API.
+      #
+      # @return [SOAP::RPC::Driver] +vzarelocator+ SOAP::RPC::Driver instance.
+      def relocator
+        @relocator ||= Virtuozzo::SOAP::Drivers::Relocator.new(@endpoint)
+      end
+  
+      ##
+      # Handle for the +vzadevm+ interface of the Virtuozzo API.
+      #
+      # @return [SOAP::RPC::Driver] +vzadevm+ SOAP::RPC::Driver instance.
+      def device
+        @device ||= Virtuozzo::SOAP::Drivers::Device.new(@endpoint)
+      end
+  
+      ##
+      # Handle for the +vzanetworkm+ interface of the Virtuozzo API.
+      #
+      # @return [SOAP::RPC::Driver] +vzanetworkm+ SOAP::RPC::Driver instance.
+      def network
+        @network ||= Virtuozzo::SOAP::Drivers::Network.new(@endpoint)
+      end
+  
+      ##
+      # Handle for the +vzaproc_info+ interface of the Virtuozzo API.
+      #
+      # @return [SOAP::RPC::Driver] +vzaproc_info+ SOAP::RPC::Driver instance.
+      def process_info
+        @process_info ||= Virtuozzo::SOAP::Drivers::ProcessInfo.new(@endpoint)
+      end
+  
+      ##
+      # Handle for the +vzaprocessmm+ interface of the Virtuozzo API.
+      #
+      # @return [SOAP::RPC::Driver] +vzaprocessm+ SOAP::RPC::Driver instance.
+      def process
+        @process ||= Virtuozzo::SOAP::Drivers::Process.new(@endpoint)
+      end
+  
+      ##
+      # Handle for the +vzaup2date+ interface of the Virtuozzo API.
+      #
+      # @return [SOAP::RPC::Driver] +vzaup2date+ SOAP::RPC::Driver instance.
+      def up2date
+        @up2date ||= Virtuozzo::SOAP::Drivers::Up2date.new(@endpoint)
+      end
+  
+      ##
+      # Handle for the +vzasupport+ interface of the Virtuozzo API.
+      #
+      # @return [SOAP::RPC::Driver] +vzasupport+ SOAP::RPC::Driver instance.
+      def support
+        @support ||= Virtuozzo::SOAP::Drivers::Support.new(@endpoint)
+      end
+
+      private
+
+      ##
+      # Disables verification of SSL certificates for all drivers.
+      #
+      def disable_ssl_verification
+        if @endpoint =~ /^https/
+          session.options['protocol.http.ssl_config.verify_mode'] = nil
+          environment.options['protocol.http.ssl_config.verify_mode'] = nil
+          template.options['protocol.http.ssl_config.verify_mode'] = nil
+          relocator.options['protocol.http.ssl_config.verify_mode'] = nil
+          device.options['protocol.http.ssl_config.verify_mode'] = nil
+          network.options['protocol.http.ssl_config.verify_mode'] = nil
+          process_info.options['protocol.http.ssl_config.verify_mode'] = nil
+          process.options['protocol.http.ssl_config.verify_mode'] = nil
+          up2date.options['protocol.http.ssl_config.verify_mode'] = nil
+          support.options['protocol.http.ssl_config.verify_mode'] = nil
+        end
+      end
+  
+      ##
+      # Sets the wiredump device for all drivers.
+      def setup_debug_mode(dev)
+        if dev == true
+          dev = STDERR
+        end
+        
+        session.wiredump_dev = dev
+        environment.wiredump_dev = dev
+        template.wiredump_dev = dev
+        relocator.wiredump_dev = dev
+        device.wiredump_dev = dev
+        network.wiredump_dev = dev
+        process_info.wiredump_dev = dev
+        process.wiredump_dev = dev
+        up2date.wiredump_dev = dev
+        support.wiredump_dev = dev
+      end
+
+      ##
+      # Performs the actual session authentication and storage of the
+      # +session_id+ value.
+      #
+      def establish_session
+        login_opts = {
+          :name => Base64.encode64(@username),
+          :password => Base64.encode64(@password),
+          :realm => @realm
+        }
+
+        resp = session.login(login_opts)
+
+        @session_id = resp.session_id || nil
+      end
+
+      ##
+      # Sets up handling of the SOAP envelope header for all outbound messages
+      # given the established +session_id+ and sets the appropriate target for
+      # each driver in turn.
+      #
+      def setup_header_handler
+        session.headerhandler << HeaderHandler.new(:session => @session_id, :target => 'sessionm')
+        environment.headerhandler << HeaderHandler.new(:session => @session_id, :target => 'vzaenvm')
+        template.headerhandler << HeaderHandler.new(:session => @session_id, :target => 'vzapackagem')
+        relocator.headerhandler << HeaderHandler.new(:session => @session_id, :target => 'vzaprelocator')
+        device.headerhandler << HeaderHandler.new(:session => @session_id, :target => 'vzadevm')
+        network.headerhandler << HeaderHandler.new(:session => @session_id, :target => 'vzanetworkm')
+        process_info.headerhandler << HeaderHandler.new(:session => @session_id, :target => 'vzaproc_info')
+        process.headerhandler << HeaderHandler.new(:session => @session_id, :target => 'vzaprocessm')
+        up2date.headerhandler << HeaderHandler.new(:session => @session_id, :target => 'vzaup2date')
+        support.headerhandler << HeaderHandler.new(:session => @session_id, :target => 'vzasupport')
+      end
+    end
+  end
+end