cloudstack_api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1a71fad5fd898a7b1c3660a34b5c9eb251049ebb
+  data.tar.gz: 3045b355845b58ccb21352d8f394cff175a0a921
+SHA512:
+  metadata.gz: 864c0045e465200e2e5b6b41706b5c8dfbfd6aedc630a552f2b4c29d833531db344d3a0b624e8373855b56276c76ef19470886ac93f6092c79d0aa852df59467
+  data.tar.gz: c8f27faf0e8175c605f32435fd2b4f17886e5c11cc18ceda50d829099e6b3067b62e465885b0ac16ba8ac2426de7ab37fb71f9aee61807b4da687a7ade358cff

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 YOURNAME
+
+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/README.rdoc

@@ -0,0 +1,123 @@
+= cloudstack_api
+
+Ruby library for the CloudStack API. Current version uses CloudStack API
+version 4.3.0 ({API Reference}[http://cloudstack.apache.org/docs/api/apidocs-4.3/TOC_Root_Admin.html])
+
+
+== Installation
+
+Cloudstack library requires Ruby 1.9.3 or later. To install, add this line to your
++Gemfile+ and run <tt>bundle install</tt>:
+
+  gem 'cloudstack_api'
+
+Gem was renamed from +cloudstack+ to +cloudstack_api+ to avoid name conflicts with CloudStack trademark.
+
+
+== Configuration
+
+By default module uses configuration from <tt>config/cloudstack.yml</tt> file. To generate it run:
+
+  rake cloudstack:install
+
+This command generates file <tt>config/cloudstack.yml</tt> which contains configuration for each environment
+
+  default: &default
+    api_key: xxxxxxxxx
+    secret_key: xxxxxxxxx
+    api_url: https://your.domain.com/client/api
+
+  production:
+    <<: *default
+
+  development:
+    <<: *default
+
+  test:
+    <<: *default
+    api_mode: test
+
+Fill in +api_url+, +api_key+ and +secret_key+ for each environment or use +default+ template.
+
+You can configure module at runtime if you need:
+
+  Cloudstack.configure do |config|
+    config.api_key = 'xxxxx'
+    config.secret_key = 'xxxxxx'
+    config.api_url = 'https://your.domain.com/client/api'
+    config.api_mode = 'test' # don't execute any command, just return signed request
+  end
+
+or set each configuration option separately:
+
+  Cloudstack.config.api_key = 'xxxxxx'
+
+== Usage
+
+To use library you need to create an instance of Cloudstack::Api class and call it methods:
+
+  @api = Cloudstack::Api.new
+  @api.execute_command('listVirtualMachines', account: 'myuser', domainid: '1bd9a980-0f11-4892-aa0b-7c434dbd6d1c')
+
+Last line returns a result hash:
+
+  {
+    :count => 1,
+    :virtualmachine => [
+        {
+                   :id => "0e061655-d982-4c2d-810e-6f3aa7d2ccde",
+                 :name => "cloudvds4509",
+          :displayname => "cloudvds4509",
+              :account => "myuser",
+             :domainid => "1bd9a980-0f11-4892-aa0b-7c434dbd6d1c",
+               :domain => "core",
+              :created => "2014-08-15T15:35:20+0000",
+                :state => "Stopped",
+             :haenable => true,
+  ...
+
+or +false+ if an error was occured. All error messages stores in an +errors+ method.
++errors+ method is a functionality of <tt>ActiveModel::Validations</tt> module.
+
+  @api.errors.messages
+
+returns:
+
+  {:base=>["could not find account user in domain 1bd9a980-0f11-4892-aa0b-7c434dbd6d1c"]}
+
+If you prefer to work with exceptions you can use functions with <tt>!</tt> suffix. For example:
+
+  begin
+    @api = Cloudstack::Api.new
+    @api.execute_command!('listVirtualMachines', account: 'myuser', domainid: '1bd9a980-0f11-4892-aa0b-7c434dbd6d1c')
+  rescue Exception => e
+    puts e.message  # => could not find account myuser in domain 1bd9a980-0f11-4892-aa0b-7c434dbd6d1c
+  end
+
+
+== Shortcuts for API commands
+
+For writing more readable code, use API commands shortcuts.
+
+  @api.list_virtual_machines(account: 'myuser', domainid: '1bd9a980-0f11-4892-aa0b-7c434dbd6d1c')
+
+is the same as:
+
+  @api.execute_command('listVirtualMachines', account: 'myuser', domainid: '1bd9a980-0f11-4892-aa0b-7c434dbd6d1c')
+
+Shortcuts commands is an underscored API commands. For example command +deployVirtualMachine+
+has +deploy_virtual_machine+ shortcut method.
+
+Exception raises methods have shotcuts too. Just add <tt>!</tt> suffix to it:
+
+  begin
+    @api.list_virtual_machines!(account: 'myuser', domainid: '1bd9a980-0f11-4892-aa0b-7c434dbd6d1c')
+  rescue Exception => e
+    puts e.message  # => could not find account myuser in domain 1bd9a980-0f11-4892-aa0b-7c434dbd6d1c
+  end
+
+
+====== TODO
+
+- Handle async jobs
+- Write documentation!!!

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Cloudstack'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/cloudstack/api.rb

@@ -0,0 +1,179 @@
+module Cloudstack
+
+  # Instance of Cloudstack::Api class uses to prepare CloudStack API request
+  # and send it to Cloudstack Management Server. Then Cludstack::Api handles
+  # a response and return it in usable type.
+
+  class Api
+    include ActiveModel::AttributeMethods
+    include ActiveModel::Validations
+
+    validate :validate_api_params
+
+    # methods with '!' suffix will raise an exception when error occurs
+    attribute_method_suffix '!'
+
+    # add api commands as methods to api instance
+    define_attribute_methods Cloudstack.config.methods
+
+
+    # Calls CloudStack API command on a remote server.
+    # Method arguments is +command+ and a list of +params+
+    # - +command+ is one of the commands described on a
+    #   {CloudStack API reference page}[http://cloudstack.apache.org/docs/api/apidocs-4.3/TOC_Root_Admin.html]
+    # - +params+ is a hash of +command+ parameters
+    #
+    # Method returns a response hash (if request was success) or
+    # raises an error else. Before raising an error it stores in an
+    # #errors object. It works like ActiveModel::Validations
+    # So error messages can be retrieved:
+    #   api_instance.errors.messages
+    #
+    # == Example
+    #
+    #   @api = Cloudstack::Api.new
+    #   @api.execute_command('some command', some_param: 'some value')   # => raises ArgumentError exception
+    #   @api.errors.messages # => {:command=>["'some command' is invalid command"]}
+    #
+
+    def execute_command!(command, params={})
+      # Clear errors from previous request
+      errors.clear
+
+      # Set local variables
+      @command = command.to_s
+      @params = params.symbolize_keys
+
+      # Validate command and parameters
+      raise ArgumentError if invalid?
+
+      # Assemble request_options
+      request_options = {
+          command: @command,
+          apikey: Cloudstack.config.api_key,
+          response: 'json'
+      }
+      request_options.merge! @params
+
+      # Generate request signature and add it to request_options
+      request_options[:signature] = sign_request(request_options)
+
+      # Generate request url with parameters
+      request_url = Cloudstack.config.api_url + '?' + request_options.to_query
+
+      # Check current mode. If mode is +test+ than command not executes,
+      # but only returns request url.
+      return request_url if Cloudstack.config.api_mode == 'test'
+
+      begin
+        # send curl request to the CloudStack server
+        curl = Curl::Easy.new(request_url)
+        curl.ssl_verify_peer = false
+        curl.perform
+
+        # handle response
+        response = JSON.parse(curl.body_str, symbolize_names: true)
+      rescue Exception => e
+        # If error occurs, it adds to instance errors
+        errors.add(:base, e.message)
+        raise e
+      end
+
+      # Checks if a command returns a CloudStack error. If error occurs,
+      # it adds to errors and excepions reises.
+      if response[:errorresponse].present?
+        errors.add(:base, response[:errorresponse][:errortext])
+        raise StandardError, response[:errorresponse][:errortext]
+      end
+
+      result = response["#{command}response".downcase.to_sym]
+
+      if result[:errortext].present?
+        errors.add(:base, result[:errortext])
+        raise StandardError, result[:errortext]
+      end
+
+      # If all pass success, returns a result hash
+      result
+    end
+
+    # Method provides the same functionality as #execute_command! except
+    # it does not raises exceptions. When error occurs, it just returns +false+.
+    # So if method returns +false+, errors message should be in #errors
+    #
+    # == Example
+    #
+    #   @api = Cloudstack::Api.new
+    #   @api.execute_command('some command', some_param: 'some value')   # => false
+    #   @api.errors.messages # => {:command=>["'some command' is invalid command"]}
+    #
+
+    def execute_command(command, options={})
+      begin
+        return execute_command!(command, options)
+      rescue
+        return false
+      end
+    end
+
+    protected
+
+    # Generates a signature for api request.
+    # Details {Signing API Requests}[http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.0.0-incubating/html/API_Developers_Guide/signing-api-requests.html]
+    def sign_request(request_options)
+      request_string = Hash[request_options.sort].to_query.downcase
+      Base64.encode64(OpenSSL::HMAC.digest( OpenSSL::Digest.new('sha1'), Cloudstack.config.secret_key, request_string)).strip
+    end
+
+    # Method provides shortcuts for api commands. For example
+    # it can be called
+    #   @api.list_virtual_machines!(parameters)
+    # instead of
+    #   @api.execute_command!('listVirtualMachines', parameters)
+    #
+    # It's useful in a command line mode. Function names will autocompletes.
+    def attribute!(attr, *args)
+      execute_command!(Cloudstack.config.method_to_command(attr), *args)
+    end
+
+    # The same as #attribute! method, but calls #execute_command method,
+    # which doesn't raise errors.
+    def attribute(attr, *args)
+      execute_command(Cloudstack.config.method_to_command(attr), *args)
+    end
+
+    # Validates api command and parameters. CloudStack API specification
+    # stores in a lib/config/api_spec.yml file. Method checks command name,
+    # parameters names and required parameters presence.
+    #
+    # If command or parameters is invalid, then corresponding error will be
+    # added to #errors
+    def validate_api_params
+      # retrieve parameters that belongs
+      allowed_params = Cloudstack.config.command_params(@command)
+
+      # if no parameters for current command then command is incorrect
+      unless allowed_params.present?
+        errors.add(:command, "'#{@command}' is invalid command")
+        return
+      end
+
+      # each parameter name should be in allowed parameters for current command
+      (@params.keys - allowed_params).each do |param|
+        errors.add(:params, "'#{param}' parameter is not allowed")
+      end
+
+      # check required parameters
+      required_params = Cloudstack.config.command_required_params(@command)
+      (required_params - @params.keys).each do |param|
+        errors.add(:params, "'#{param}' parameter is required")
+      end
+
+      # # each parameter value should be a string
+      # @params.each do |key,value|
+      #   errors.add(:params, "'#{value}' parameter should be a String") unless value.is_a? String
+      # end
+    end
+
+  end
+end

data/lib/cloudstack/configuration.rb

@@ -0,0 +1,59 @@
+class Configuration
+
+  attr_accessor :api_key,
+                :secret_key,
+                :api_url,
+                :api_spec,
+                :api_mode
+
+  def initialize
+    if defined?(Rails) and File.exist?(File.expand_path('config/cloudstack.yml', Rails.root))
+      config = YAML.load_file(File.expand_path('config/cloudstack.yml', Rails.root))[Rails.env]
+
+      @api_key = config['api_key'] if config['api_key'].present?
+      @secret_key = config['secret_key'] if config['secret_key'].present?
+      @api_url = config['api_url'] if config['api_url'].present?
+      @api_mode = config['api_mode'] if config['api_mode'].present?
+    end
+    @api_spec = YAML.load_file(File.expand_path('../../config/api_spec.yml', __FILE__))
+
+    # contain map of underscore api commands relative to camelize
+    @method_to_command = Hash[ @api_spec.keys.map {|key| [key.underscore.to_sym, key]} ]
+  end
+
+
+  ##
+  # return an array of api methods. Method is an underscored command.
+  # it was done, because ruby methods should be underscored, but CloudStack
+  # uses camelCased command names
+  def methods
+    @api_methods ||= @api_spec.keys.map{ |key| key.underscore.to_sym }
+  end
+
+
+  ##
+  # return an array of available api commands. It uses in validations and so on.
+  def commands
+    @api_commands ||= @api_spec.keys
+  end
+
+
+  ##
+  # convert underscored method name to camelCased command
+  def method_to_command(command)
+    @method_to_command[command.to_sym]
+  end
+
+  ##
+  # return an array of given command parameters
+  def command_params(command)
+    @api_spec[command.to_s]['params'].keys.map(&:to_sym) if @api_spec[command.to_s]
+  end
+
+  ##
+  # return an array of given command required parameters
+  def command_required_params(command)
+    @api_spec[command.to_s]['params'].map {|k,v| k.to_sym if v['required']}.compact
+  end
+
+end

data/lib/cloudstack/railtie.rb

@@ -0,0 +1,10 @@
+require 'rails'
+module Cloudstack
+  class Railtie < Rails::Railtie
+    railtie_name :cloudstack
+
+    rake_tasks do
+      load 'tasks/cloudstack_tasks.rake'
+    end
+  end
+end

data/lib/cloudstack/version.rb

@@ -0,0 +1,3 @@
+module Cloudstack
+  VERSION = '1.0.0'
+end

data/lib/cloudstack.rb

@@ -0,0 +1,19 @@
+module Cloudstack
+  require 'cloudstack/railtie' if defined?(Rails)
+  require 'cloudstack/configuration'
+  autoload :Api, 'cloudstack/api'
+  require 'curb'
+
+  # Gives access to the current configuration
+  def self.config
+    @configuration ||= Configuration.new
+  end
+
+  # Allows easy setting of multiple configuration options. See Configuration
+  # for all available options.
+  def self.configure
+    config = self.config
+    yield(config)
+  end
+
+end