cloud_stack_client 0.0.1

data/lib/cloud_stack_client/connector.rb

@@ -0,0 +1,155 @@
+# The Connector assists in the interaction with the CloudStack API using a simple interface.
+
+require "cloud_stack_client/api.rb"
+
+# Simple class to interact with the CloudStack API
+# 
+# @example The server URI is passed on instance creation
+#   connector = CloudStackClient::Connector.new('http://example.com/client/api')
+#   # or
+#   connector = CloudStackClient::Connector.new(:api_uri => 'https://example.com/client/api', :api_key => 'MyKeY', :secret_key => 'mYsEcReT')
+# @example Login with Username, Passwort and Domain if API Key and Secret Key are not available
+#   connector.login('MyUser', 'MyPassword', 'MyDomain') # => true or false
+# @example Execute an arbitrary command
+#   connector.listVirtualMachines # => Raw result record as REXML::Document
+#   connector.listVirtualMachines(:response => :json, :state => :running) # => Hash with result record
+class CloudStackClient::Connector
+  # Connection credentials and settings. Defaults to {CloudStackClient::API_DEFAULTS}.
+  # @return [Hash]
+  attr_accessor :config
+  
+  # Create API Connector.
+  # 
+  # Configuration can passed as configuration Hash or as String containing the API URL.
+  # 
+  # @param config [String, Hash] URI of the Service API or Hash with configuration parameters
+  # @see CloudStackClient::API_DEFAULTS
+  def initialize(config = {})
+    if config.is_a? String
+      if config.length > 0
+        config = {:api_uri => config}
+        if config[:api_uri].index("/api")
+          config[:web_uri] = config[:api_uri].sub("/api", "")
+        end
+      else
+        config = {}
+      end
+    end
+    @config = CloudStackClient::API_DEFAULTS.dup
+    config.each {|key, value| @config[key.to_sym] = value}
+    @credentials = {}
+    @credentials[:api_key] = @config[:api_key] if @config[:api_key]
+    @credentials[:secret_key] = @config[:secret_key] if @config[:secret_key]
+  end
+  
+  # Login with username and plain text password
+  # 
+  # @param username [String]
+  # @param password [String] Plain text password
+  # @param domain [String] Login Domain. The / prefix can be omitted
+  # @return [Boolean] true if successful
+  def login(username, password, domain = "")
+    password ||= ""
+    login_hashed username, CloudStackClient::Helpers::hash_password(password), domain
+  end
+  
+  # Login with username and hashed password
+  # 
+  # @param username [String]
+  # @param password_hash [String] Password hash
+  # @param domain [String] Login Domain. The / prefix can be omitted
+  # @return [Boolean] true if successful
+  # @see CloudStackClient::Helpers::hash_password
+  def login_hashed(username, password_hash, domain = "")
+    result = CloudStackClient::API::get_credentials @config[:api_uri], username, password_hash, domain, @config[:http_method], @config[:ssl_check]
+    if result
+      @credentials = result
+      true
+    else
+      false
+    end
+  end
+  
+  # Login with API Key and Secret Key
+  # 
+  # @param api_key [String]
+  # @param secret_key [String]
+  # @return [Boolean] true if successful
+  def login_with_keys(api_key, secret_key)
+    if CloudStackClient::API::verify_keys(@config[:api_uri], api_key, secret_key, @config[:http_method], @config[:ssl_check])
+      @credentials[:api_key] = api_key
+      @credentials[:secret_key] = secret_key
+      true
+    else
+      false
+    end
+  end
+  
+  # Check whether valid login credentials are present
+  # 
+  # @return [Boolean]
+  def authenticated?
+    if @credentials.any? && query({:command => "listCapabilities"})
+      true
+    else
+      false
+    end
+  end
+  
+  # Send a command
+  # 
+  # @param parameters [Hash, Array] Hash or Array of [Key, Value] pairs containing all query parameters
+  # @return [REXML::Document, Hash, String] The query result depending on the HTTP response content type 
+  def query(parameters)
+    CloudStackClient::API::query(@config[:api_uri], parameters, @credentials, @config[:http_method], @config[:ssl_check])
+  end
+
+  # Send a command and merge all result pages
+  # 
+  # If the result spans multiple pages, multiple calls are executed to retrieve all pages. These will be returned as one.
+  # 
+  # @param parameters [Hash, Array] Hash or Array of [Key, Value] pairs containing all query parameters
+  # @return [REXML::Document, Hash, String] The query result depending on the HTTP response content type 
+  def query_all_pages(parameters)
+    CloudStackClient::API::query_with_auto_paging(@config[:api_uri], parameters, @credentials, @config[:page_size], @config[:http_method], @config[:ssl_check])
+  end
+  
+  private
+
+  # Dynamic methods are passed as commands to CloudStack
+  # 
+  # @example Use dynamic methods as commands
+  #   cs_connector = CloudStackClient::Connector.new "https://example.com/client/api"
+  #   cs_connector.login "Me", "MyPass", "MyDomain"
+  #   response = cs_connector.listVirtualMachines(:response => :json, :state => :running)
+  #   if response.has_key? "listvirtualmachinesresponse"
+  #     vms = response["listvirtualmachinesresponse"]["virtualmachine"]
+  #     cs_connector.stopVirtualMachine :id => vms.first["id"]
+  #   end
+  # 
+  # @param method_name [String] Name of the command
+  # @param parameters [Hash, Array] command parameters
+  # @param disable_auto_paging [Boolean] (optional) If true the command will be executed with manual paging
+  # @return [REXML::Document, Hash] Result of the query
+  def method_missing(*args)
+    name = args.shift
+    parameters = args.shift
+    auto_paging = !args.shift
+    if parameters.is_a?(Hash) && !parameters.has_key?(:command)
+      parameters[:command] = name
+    elsif parameters.is_a?(Array) && !parameters.find {|pos| pos.is_a?(Array) && pos[0] == :command}
+      parameters << [:command => name]
+    else
+      parameters = {:command => name}
+    end
+    if auto_paging && name.to_s.downcase.start_with?("list")
+      query_all_pages(parameters)
+    else
+      query(parameters)
+    end
+  end
+  
+  def respond_to_missing?(name, private)
+    true
+  end
+end

data/lib/cloud_stack_client/definitions.rb

@@ -0,0 +1,29 @@
+module CloudStackClient
+  # Default values used by CloudStackClient
+  API_DEFAULTS = {
+    :web_uri => "",
+    :api_uri => "",
+    :ssl_check => true,
+    :http_method => :post,
+    :login_parameter => "loginUrl",
+    :page_size => 500,
+    :timestamp_offset => 3600
+  }.freeze
+  
+  # Translation of the usage types as returned by getUsageRecords
+  USAGE_MAP = {
+    1  => :running_vm,
+    2  => :allocated_vm,
+    3  => :ip_address,
+    4  => :network_bytes_send,
+    5  => :network_bytes_received,
+    6  => :volume,
+    7  => :template,
+    8  => :iso,
+    9  => :snapshot,
+    11 => :load_balancer_policy,
+    12 => :port_forwarding_rule,
+    13 => :network_offering,
+    14 => :vpn_users
+  }.freeze
+end

data/lib/cloud_stack_client/helpers.rb

@@ -0,0 +1,7 @@
+# Shared helper functions
+module CloudStackClient::Helpers
+  # Default password hash algorithm
+  def self.hash_password(password)
+    Digest::MD5.hexdigest(password)
+  end
+end

data/lib/cloud_stack_client/version.rb

@@ -0,0 +1,4 @@
+module CloudStackClient
+  # Release version number
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: cloud_stack_client
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Roman Messer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-24 00:00:00.000000000 Z
+dependencies: []
+description: Execute any command against a CloudStack Infrastructure. Also contains
+  a commandline utility with auto paging and support to read credentials from a config
+  file.
+email:
+- roman.messer@ict-cloud.com
+executables:
+- cloud-stack.rb
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .hgignore
+- .yardopts
+- Gemfile
+- MIT-LICENSE.txt
+- README.md
+- Rakefile
+- assets/cacert.pem
+- bin/cloud-stack.rb
+- cloud_stack_client.gemspec
+- lib/cloud_stack_client.rb
+- lib/cloud_stack_client/api.rb
+- lib/cloud_stack_client/cli.rb
+- lib/cloud_stack_client/connector.rb
+- lib/cloud_stack_client/definitions.rb
+- lib/cloud_stack_client/helpers.rb
+- lib/cloud_stack_client/version.rb
+homepage: 
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: A simple library to work with the CloudStack API.
+test_files: []
+has_rdoc: