vcloud 0.0.1.1

data/lib/vcloud/constants.rb

@@ -0,0 +1,38 @@
+module VCloud
+  module Constants
+    
+    # vCloud Director API versions
+    module Version
+      V0_9 = '0.9' 
+      V1_5 = '1.5'
+      V5_1 = '5.1'
+    end    
+
+    ACCEPT_HEADER = 'application/*+xml'
+    XML_ENCODING = 'UTF-8'
+    
+    # vCloud Director MIME types
+    module ContentType
+      CATALOG                          = 'application/vnd.vmware.vcloud.catalog+xml'
+      CATALOG_ITEM                     = 'application/vnd.vmware.vcloud.catalogItem+xml'
+      INSTANTIATE_VAPP_TEMPLATE_PARAMS = 'application/vnd.vmware.vcloud.instantiateVAppTemplateParams+xml'
+      NETWORK_CONFIG_SECTION           = 'application/vnd.vmware.vcloud.networkConfigSection+xml'
+      ORG                              = 'application/vnd.vmware.vcloud.org+xml'
+      ORG_LIST                         = 'application/vnd.vmware.vcloud.orgList+xml'      
+      ORG_NETWORK                      = 'application/vnd.vmware.vcloud.orgNetwork+xml'
+      TASK                             = 'application/vnd.vmware.vcloud.task+xml'
+      UNDEPLOY_VAPP_PARAMS             = 'application/vnd.vmware.vcloud.undeployVAppParams+xml'  
+      VAPP                             = 'application/vnd.vmware.vcloud.vApp+xml'
+      VAPP_TEMPLATE                    = 'application/vnd.vmware.vcloud.vAppTemplate+xml'
+      VDC                              = 'application/vnd.vmware.vcloud.vdc+xml'
+    end
+    
+    # vCloud Director API XML namespaces
+    module NameSpace
+      V1_5 = 'http://www.vmware.com/vcloud/v1.5'
+      OVF = 'http://schemas.dmtf.org/ovf/envelope/1'
+      XSI = 'http://www.w3.org/2001/XMLSchema-instance'
+    end      
+
+  end
+end

data/lib/vcloud/errors.rb

@@ -0,0 +1,31 @@
+module VCloud
+  module Errors
+    HTTPMessage = {
+        200 => {:short_message => 'OK', :message => 'The request is valid and was completed. The response includes a document body.'},
+        201 => {:short_message => 'Created', :message => 'The request is valid. The requested object was created and can be found at the URL specified in the Location header.'},
+        202 => {:short_message => 'Accepted', :message => 'The request is valid and a task was created to handle it. This response is usually accompanied by a Task element.'},
+        204 => {:short_message => 'No Content', :message => 'The request is valid and was completed. The response does not include a body.'},
+        303 => {:short_message => 'See Other', :message => 'The response to the request can be found at the URL specified in the Location header.'},
+        400 => {:short_message => 'Bad Request', :message => 'The request body is malformed, incomplete, or otherwise invalid.'},
+        401 => {:short_message => 'Unauthorized', :message => 'An authorization header was expected but not found.'},
+        403 => {:short_message => 'Forbidden', :message => 'The requesting user does not have adequate privileges to access one or more objects specified in the request.'},
+        404 => {:short_message => 'Not Found', :message => 'One or more objects specified in the request could not be found in the specified container.'},
+        405 => {:short_message => 'Method Not Allowed', :message => 'The HTTP method specified in the request is not supported for this object.'},
+        500 => {:short_message => 'Internal Server Error', :message => 'The request was received but could not be completed because of an internal error at the server.'},
+        501 => {:short_message => 'Not Implemented', :message => 'The server does not implement the request.'},
+        503 => {:short_message => 'Service Unavailable', :message => 'One or more services needed to complete the request are not available on the server.'}
+      }
+  end
+
+  class VCloudError < StandardError
+    attr_reader :message, :major_error_code, :minor_error_code, :vendor_specific_error_code, :stack_trace
+
+    def initialize(message, major_error_code, minor_error_code = nil, vendor_specific_error_code = nil, stack_trace = nil)
+      @message                    = message
+      @major_error_code           = major_error_code
+      @minor_error_code           = minor_error_code
+      @vendor_specific_error_code = vendor_specific_error_code
+      @stack_trace                = stack_trace
+    end
+  end
+end

data/lib/vcloud/parses_xml.rb

@@ -0,0 +1,33 @@
+module VCloud
+  module ParsesXml
+    def self.included(base)
+      base.send(:include, HappyMapper)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def has_links
+        self.class_eval do
+          has_many :links, 'VCloud::Link', :xpath => '.'
+        end
+      end
+
+      def has_default_attributes
+        self.class_eval do
+          attribute :id, 'String'
+          attribute :type, 'String'
+          attribute :name, 'String'
+          attribute :href, 'String'           
+        end
+      end
+      
+      def from_xml(xml)
+        parse(xml)
+      end
+    end
+
+    def parse_xml(xml)
+      parse(xml)
+    end
+  end
+end

data/lib/vcloud/rest_api.rb

@@ -0,0 +1,91 @@
+module VCloud
+  module RestApi
+
+    def refresh(session = self.session)
+      http_opts = build_generic_http_opts(@href, nil, nil, session, {})
+      http_opts.merge!(:method => 'get')
+      http_opts[:headers][:accept] = self.class.type+";version=#{session.api_version}"
+      response = http_request(http_opts)
+      parse_response(response)
+    end
+          
+    def create
+    end
+    
+    def update
+    end
+    
+    def delete(url, payload, content_type, session = self.session, opts={})
+      http_opts = build_generic_http_opts(url, payload, content_type, session, opts)
+      http_opts.merge!(:method => 'delete')
+      http_request(http_opts)     
+    end
+    
+    def post(url, payload, content_type, session = self.session, opts={})
+      http_opts = build_generic_http_opts(url, payload, content_type, session, opts)
+      http_opts.merge!(:method => 'post')
+      http_request(http_opts)
+    end    
+
+    def http_request(http_opts)
+      request = RestClient::Request.new(http_opts)    
+      response = request.execute { |response, request|
+        case response.code
+        when 200, 201, 202, 204 then
+          return response.body
+        when 303 then
+          # 303 See Other, provides a Location header
+          # TODO: How do we handle this?
+          return response.body
+        when 400, 401, 403, 404, 405, 500, 501, 503 then
+
+          # If there is a body, try to parse as Error xml doc and raise exception
+          if not response.body.strip.empty?
+            error = VCloud::Error.from_xml(response.body)
+            if error.instance_of?(VCloud::Error)
+              raise VCloud::VCloudError.new(
+                error.message, 
+                error.major_error_code, 
+                error.minor_error_code, 
+                error.vendor_specific_error_code, 
+                error.stack_trace)
+            end
+          end
+          
+          # No body was supplied or body wasn't an Error xml doc, create and raise exception
+                    
+          major_error_code = response.code
+          short_message = VCloud::Errors::HTTPMessage[response.code][:short_message]
+          long_message  = VCloud::Errors::HTTPMessage[response.code][:message]          
+          message       = "#{short_message} - #{long_message}"
+        
+          raise VCloud::VCloudError.new(message, major_error_code)          
+        else
+          raise VCloud::VCloudError.new('An unexpected return code was received', response.code)
+        end
+      }
+         
+      response.nil? ? '' : response.body
+    
+    rescue OpenSSL::SSL::SSLError => err
+      raise VCloud::VCloudError.new("Failed to verify SSL certifcate at API target URL.  Either verify that the target server has a properly named SSL certificate or create the client to skip ssl verification.  Eg: session = VCloud::Client.new('https://api.vcloud.com', '1.5', :verify_ssl => false)", 'na')
+    end
+   
+    def build_generic_http_opts(url, payload, content_type, session, opts)
+      headers = {:accept => VCloud::Constants::ACCEPT_HEADER+";version=#{session.api_version}"}.merge(session.token)
+      headers.merge!(:content_type => content_type) if content_type
+      {
+        :url        => url,
+        :payload    => payload,
+        :verify_ssl => session.verify_ssl,
+        :headers    => headers
+      }.merge(opts)
+    end
+    
+    #override to provide custom parsing
+    def parse_response(response)
+      parse_xml(response.body)
+    end
+    
+  end
+end

data/lib/vcloud/user.rb

@@ -0,0 +1,5 @@
+module VCloud   
+  Dir[File.expand_path("../user/*.rb", __FILE__)].each do |file|
+    require file
+  end
+end

data/lib/vcloud/user/catalog.rb

@@ -0,0 +1,32 @@
+module VCloud
+  # Contains a collection of CatalogItem references
+  class Catalog < BaseVCloudEntity
+
+    has_type VCloud::Constants::ContentType::CATALOG
+    tag 'Catalog'
+    has_links
+    has_default_attributes
+    wrap 'CatalogItems' do
+      has_many :catalog_item_references, 'VCloud::Reference', :tag => "CatalogItem"
+    end
+    element :is_published, Boolean, :tag => 'IsPublished'
+
+    # Returns a hash of of all CatalogItem references, keyed by the CatalogItem name
+    #
+    # @return [Hash{String => VCloud::Reference}] Reference to all CatalogsItems in the Catalog, keyed by name
+    def get_catalog_item_references_by_name
+      Hash[catalog_item_references.collect{ |i| [i.name, i] }]
+    end
+    
+    # Retrieves an CatalogItem, assuming the user has access to it
+    #
+    # @param [String] name CatalogItem name
+    # @param [VCloud::Client] session Session to use to retrieve the CatalogItem
+    # @return [VCloud::CatalogItem] CatalogItem object
+    def get_catalog_item_from_name(name, session = self.session)
+      catalog_items = get_catalog_item_references_by_name
+      item = catalog_items[name] or return nil
+      CatalogItem.from_reference(item, session)
+    end
+  end
+end

data/lib/vcloud/user/catalog_item.rb

@@ -0,0 +1,10 @@
+module VCloud
+  # Contains a reference to a VappTemplate or Media object and related metadata
+  class CatalogItem < BaseVCloudEntity
+    has_type VCloud::Constants::ContentType::CATALOG_ITEM
+    tag 'CatalogItem'
+    has_default_attributes
+    has_links
+    has_one :entity_reference, 'VCloud::Reference', :tag => 'Entity'
+  end
+end

data/lib/vcloud/user/error.rb

@@ -0,0 +1,12 @@
+module VCloud
+  class Error
+    include ParsesXml
+    
+    tag 'Error'
+    attribute :message,                     String
+    attribute :major_error_code,            Integer,  :tag => "majorErrorCode"
+    attribute :minor_error_code,            String,   :tag => "minorErrorCode"
+    attribute :vendor_specific_error_code,  String,   :tag => "vendorSpecificErrorCode"
+    attribute :stack_trace,                 String,   :tag => "stackTrace"
+  end
+end

data/lib/vcloud/user/instantiate_vapp_template_params.rb

@@ -0,0 +1,36 @@
+module VCloud
+  # Represents vApp template instantiation parameters
+  class InstantiateVAppTemplateParams
+    include ParsesXml
+
+    register_namespace 'xmlns', VCloud::Constants::NameSpace::V1_5
+    tag 'InstantiateVAppTemplateParams'
+    attribute :name,        String
+    attribute :deploy,      Boolean
+    attribute :power_on,    Boolean,  :tag => 'powerOn'
+    element   :description, String,   :tag => 'Description'
+    wrap 'InstantiationParams' do
+      has_one :network_config_section, 'VCloud::NetworkConfigSection', :tag => 'NetworkConfigSection'
+    end
+    element :source_reference,    'VCloud::Reference',  :tag => 'Source'
+    element :is_source_delete,    Boolean,              :tag => 'IsSourceDelete'
+    element :all_eulas_accepted,  Boolean,              :tag => 'AllEULAsAccepted'
+    
+    # A new instance of InstantiateVAppTemplateParams
+    #
+    # @param [String] name Name of the vApp
+    # @param [Boolean] deploy True if the vApp should be deployed at instantiation. Defaults to true.
+    # @param [Boolean] power_on True if the vApp should be powered-on at instantiation. Defaults to true.
+    # @param [String] description Description of the vApp
+    # @param [Boolean] all_eulas_accepted True confirms acceptance of all EULAs in a vApp template. Instantiation fails if this element is missing, empty, or set to false and one or more EulaSection elements are present.
+    # @param [Boolean] is_source_delete Set to true to delete the source object after the operation completes.
+    def initialize
+      @name = ''
+      @deploy = true
+      @power_on = false
+      @description = ''
+      @all_eulas_accepted = false
+      @is_source_delete = false
+    end
+  end
+end

data/lib/vcloud/user/link.rb

@@ -0,0 +1,30 @@
+module VCloud
+  # Defines a hyper-link with a relationship, hyper-link reference, and an optional MIME type
+  class Link
+    include HappyMapper
+    
+    tag 'Link'
+    attribute :rel, 'String'
+    attribute :type, 'String'
+    attribute :name, 'String'
+    attribute :href, 'String'
+
+    # A new instance of Link
+    #
+    # @param args [Hash{String => String}] Named arguments, 'rel', 'type', 'name' and 'href'
+    def initialize(args = {})
+      @rel = args[:rel]
+      @type = args[:type]
+      @name = args[:name]
+      @href = args[:href]
+    end
+
+    # Parses XML to produce a VCloud::Link
+    #
+    # @param [String] xml XML to parse
+    # @return [VCloud::Link] Link object parsed from the XML
+    def self.from_xml(xml)
+      parse(xml)
+    end
+  end
+end

data/lib/vcloud/user/network_config.rb

@@ -0,0 +1,20 @@
+module VCloud
+  # Represents a vApp network configuration
+  class NetworkConfig
+    include ParsesXml
+
+    tag 'NetworkConfig'
+    attribute :network_name, String, :tag => 'networkName'
+    wrap 'Configuration' do     
+      element :parent_network_reference, 'VCloud::Reference', :tag => 'ParentNetwork'
+      element :fence_mode, String, :tag => 'FenceMode'
+    end
+    
+    # Networking fence modes
+    module FenceMode
+      BRIDGED = 'bridged'
+      ISOLATED = 'isolated'
+      NAT = 'natRouted'
+    end    
+  end
+end

data/lib/vcloud/user/network_config_section.rb

@@ -0,0 +1,20 @@
+module VCloud
+  # Container for vApp networks
+  class NetworkConfigSection
+    include ParsesXml
+  
+    register_namespace 'xmlns', VCloud::Constants::NameSpace::V1_5
+    register_namespace 'ovf', VCloud::Constants::NameSpace::OVF
+
+    tag 'NetworkConfigSection'
+    attribute :href,            String
+    attribute :type,            String
+    element   :info,            String,                   :tag => 'Info', :namespace => 'ovf'
+    has_many  :network_configs, 'VCloud::NetworkConfig',  :tag => 'NetworkConfig'
+    
+    def initialize
+      @info = 'Configuration parameters for logical networks'
+      @network_configs = []
+    end
+  end
+end

data/lib/vcloud/user/org.rb

@@ -0,0 +1,69 @@
+module VCloud
+  # An org contains links to VDCs, Catalogs, and Org Networks
+  class Org < BaseVCloudEntity
+    
+    has_type VCloud::Constants::ContentType::ORG
+    tag 'Org'
+    has_links
+    has_default_attributes
+    element :description, String, :tag => "Description"
+    element :full_name, String, :tag => "FullName"
+    
+    # Returns all links to VDCs
+    #
+    # @return [Array<VCloud::Link>] Array of Links to VDCs  
+    def vdc_links
+      @links.select {|l| l.type == VCloud::Constants::ContentType::VDC}
+    end
+    
+    # Returns all links to Catalogs
+    #
+    # @return [Array<VCloud::Link>] Array of Links to Catalogs
+    def catalog_links
+      @links.select {|l| l.type == VCloud::Constants::ContentType::CATALOG}
+    end
+
+    # Returns all links to OrgNetworks
+    #
+    # @return [Array<VCloud::Link>] Array of Links to OrgNetworks
+    def org_network_links
+      @links.select {|l| l.type == VCloud::Constants::ContentType::ORG_NETWORK}
+    end
+    
+    # Returns a hash of of all Catalog links keyed by the Catalog name
+    #
+    # @return [Hash{String => VCloud::Link}] Links to all Catalogs in the Org, keyed by name
+    def get_catalog_links_by_name
+      Hash[catalog_links.collect { |l| [l.name, l] }]
+    end
+    
+    # Retrieves an Catalog, assuming the user has access to it
+    #
+    # @param [String] name Catalog name
+    # @param [VCloud::Client] session Session to use to retrieve the Catalog
+    # @return [VCloud::Catalog] Catalog object
+    def get_catalog_from_name(name, session = self.session)
+      catalogs = get_catalog_links_by_name
+      link = catalogs[name] or return nil
+      Catalog.from_reference(link, session)
+    end
+    
+    # Returns a hash of of all VDCs links keyed by the Catalog name
+    #
+    # @return [Hash{String => VCloud::Link}] Links to all VDCs in the Org, keyed by name
+    def get_vdc_links_by_name
+      Hash[vdc_links.collect { |l| [l.name, l] }]
+    end
+    
+    # Retrieves a VDC, assuming the user has access to it
+    #
+    # @param [String] name VDC name
+    # @param [VCloud::Client] session Session to use to retrieve the VDC
+    # @return [VCloud::Vdc] VDC object
+    def get_vdc_from_name(name, session = self.session)
+      links = get_vdc_links_by_name
+      link = links[name] or return nil
+      Vdc.from_reference(link, session)
+    end    
+  end
+end

data/lib/vcloud/user/org_list.rb

@@ -0,0 +1,10 @@
+module VCloud
+  # Represents a list of organizations
+  class OrgList < BaseVCloudEntity
+    include ParsesXml
+    has_type VCloud::Constants::ContentType::ORG_LIST
+    has_default_attributes
+    tag 'OrgList'
+    has_many :org_references, 'VCloud::Reference', :tag => 'Org'
+  end
+end