right_cloud_api_base 0.1.0

data/lib/base/routines/response_parser.rb

@@ -0,0 +1,79 @@
+#--
+# Copyright (c) 2013 RightScale, Inc.
+#
+# 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.
+#++
+
+module RightScale
+  module CloudApi
+
+    # The routine parses the current response.
+    # 
+    # The supportes content-types are: xml and json.
+    # In the case of any other content-type it does nothing.
+    #
+    class ResponseParser < Routine
+
+      # Main entry point.
+      #
+      def process
+        # There is no way to parse an IO response
+        return nil if data[:response][:instance].is_io?
+
+        xml_parser   = Utils::get_xml_parser_class(data[:options][:xml_parser])
+        content_type = (data[:response][:instance].headers || {})["content-type"].to_s
+        body         = data[:response][:instance].body.to_s
+
+        # If it was explicitly requested not to parse the response then return it as is.
+        if data[:options][:raw_response]
+          data[:result] = body
+          return
+        end
+
+        # Find the appropriate parser.
+        parser = if body._blank?
+                   Parser::Plain
+                 else
+                   case content_type
+                   when /xml/              then xml_parser
+                   when /json|javascript/  then Parser::Json
+                   else
+                     if data[:response][:instance].body.to_s[/\A<\?xml /]
+                       # Sometimes Amazon does not set a proper header
+                       xml_parser
+                     else
+                       Parser::Plain
+                     end
+                   end
+                 end
+        # Parse the response
+        with_timer("Response parsing with #{parser}") do
+          options = {}
+          options[:encoding] = 'UTF-8' if /utf-8/i === content_type
+          #
+          cloud_api_logger.log("Attempting to parse cloud response with: '#{options[:encoding] || 'DEFAULT'}' encoding", :response_parser)
+          data[:response][:parsed] = parser::parse(body, options)
+        end
+        data[:result] = data[:response][:parsed]
+      end
+    end
+    
+  end
+end

data/lib/base/routines/result_wrapper.rb

@@ -0,0 +1,75 @@
+#--
+# Copyright (c) 2013 RightScale, Inc.
+#
+# 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.
+#++
+
+module RightScale
+  module CloudApi
+
+    # The Routine adds metadata to the result.
+    #
+    # @example:
+    #  response = ec2.DescribeSecurityGroups #=> A list of SecurityGroups
+    #  response.metadata #=>
+    #    {:headers=>
+    #      {"content-type"=>["text/xml;charset=UTF-8"],
+    #       "transfer-encoding"=>["chunked"],
+    #       "date"=>["Fri, 22 Feb 2013 00:02:43 GMT"],
+    #       "server"=>["AmazonEC2"]},
+    #     :code=>"200",
+    #     :cache=>
+    #      {:key=>"DescribeSecurityGroups",
+    #       :record=>
+    #        {:timestamp=>2013-02-22 00:02:44 UTC,
+    #         :md5=>"0e3e12e1c18237d9f9510e90e7b8950e",
+    #         :hits=>0}}}
+    #
+    class ResultWrapper < Routine
+
+      class Result < BlankSlate
+        attr_reader :metadata
+
+        def initialize(response, metadata)
+          @response = response
+          @metadata = metadata
+        end
+
+        # Feed all the missing methods to the original object.
+        def method_missing(method, *params, &block)
+          @response.send(method, *params, &block)
+        end
+      end
+
+      # Main entry point.
+      #
+      def process
+        cache = data._at(:vars, :cache, :default => nil)
+        metadata = {}
+        metadata[:headers] = data[:response][:instance].headers
+        metadata[:code]    = data[:response][:instance].code
+        metadata[:cache]   = cache if cache
+        #
+        data[:result] = Result::new(data[:result], metadata)
+      end
+    end
+    
+  end
+end

data/lib/base/routines/retry_manager.rb

@@ -0,0 +1,106 @@
+#--
+# Copyright (c) 2013 RightScale, Inc.
+#
+# 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.
+#++
+
+module RightScale
+  module CloudApi
+
+    # The routine is responsible for retries/reiterations.
+    #
+    # If retries are enabled then a singe API call may perform upto DEFAULT_RETRY_COUNT request
+    # attempts who may take upto DEFAULT_REITERATION_TIME secsons.
+    #
+    class RetryManager < Routine
+      class Error < CloudApi::HttpError
+      end
+      
+      DEFAULT_RETRY_COUNT      =   2
+      DEFAULT_REITERATION_TIME =  10
+      DEFAULT_SLEEP_TIME       = 0.2
+      
+      # Retries manager.
+      # 
+      # The manager usually takes the very first position in routines chain.
+      # It just increments its counters if we did not reach a possible count of retries or
+      # complains if there are no attempts left or if API request time is over.
+      #
+      # There are 2 possible reasons for a retry to be performed:
+      #  1. There was a redirect request (HTTP 3xx code)
+      #  2. There was an error (HTTP 5xx, 4xx) and
+      #
+      def process
+        retry_options    = data[:options][:retry]           || {}
+        max_retry_count  = retry_options[:count]            || DEFAULT_RETRY_COUNT
+        reiteration_time = retry_options[:reiteration_time] || DEFAULT_REITERATION_TIME
+        sleep_time       = retry_options[:sleep_time]       || DEFAULT_SLEEP_TIME
+        
+        # Initialize things on the first run for the current request.
+        unless data[:vars][:retry]
+          data[:vars][:retry]              = {}
+          data[:vars][:retry][:count]      = 0
+          data[:vars][:retry][:sleep_time] = 0
+          # if body is a IO object - remember its initial position in a file
+          data[:vars][:retry][:orig_body_stream_pos] = data[:request][:body].is_a?(IO) && data[:request][:body].pos
+        else
+          # Increment retry attempts count
+          data[:vars][:retry][:count] += 1
+        end
+        
+        # Complain on any issue
+        if max_retry_count < @data[:vars][:retry][:count]
+          error_message = "RetryManager: No more retries left."
+        elsif Time.now > @data[:vars][:system][:started_at] + reiteration_time
+          error_message = "RetryManager: Retry timeout of #{reiteration_time} seconds has been reached."
+        end
+
+        # Raise exception if request runs out-of-time or attempts.
+        if error_message
+          http_data     = @data[:vars][:retry][:http]
+          http_code     = http_data && http_data[:code]
+          http_message  = http_data && http_data[:message]
+          error_message = "#{http_message}\n#{error_message}" if http_message
+          raise Error::new(http_code, error_message)
+        end
+
+        # Continue (with a delay when needed)
+        if data[:vars][:retry][:sleep_time] > 0
+          cloud_api_logger.log("Sleeping for #{data[:vars][:retry][:sleep_time]} seconds before retry attempt ##{data[:vars][:retry][:count]}", :retry_manager)
+          sleep data[:vars][:retry][:sleep_time]
+          data[:vars][:retry][:sleep_time] *= 2
+        else
+          data[:vars][:retry][:sleep_time] = sleep_time
+        end
+        
+        # Restore file pointer in IO body case.
+        if data[:request][:instance]                          &&
+           data[:request][:instance].is_io?                   &&
+           data[:request][:instance].body.respond_to?('pos')  &&
+           data[:request][:instance].body.respond_to?('pos=') &&
+           data[:request][:instance].body.pos != data[:vars][:retry][:orig_body_stream_pos]
+          cloud_api_logger.log("Restoring file position to #{data[:vars][:retry][:orig_body_stream_pos]}", :retry_manager)
+          data[:request][:instance].body.pos = data[:vars][:retry][:orig_body_stream_pos]
+        end
+      end
+    end
+    
+  end
+end

data/lib/base/routines/routine.rb

@@ -0,0 +1,98 @@
+#--
+# Copyright (c) 2013 RightScale, Inc.
+#
+# 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.
+#++
+
+module RightScale
+  module CloudApi
+
+    # This is a parent class for all the other routines.
+    #
+    # The routine is a very simple object that does a simple task in the API call processing stack
+    # and exits. In most cases a single routine knows nothing about any other routines. It just
+    # takes incoming params from @data hash, processes it and stores back to the @adata attribute.
+    #
+    class Routine
+      attr_reader :data
+
+      # Initializes the @data attribute. Is called before *process* method.
+      #
+      # @param [Hash] data See ApiManager for better explanation what data is.
+      #
+      def reset(data=nil)
+        @data = data
+      end
+
+      # Main entry point. The method must be overriden by sub-classes.
+      def process
+        raise Error::new("This method should be implemented by a subclass")
+      end
+
+      # Initialize and process the routine. Is usially called from unit tests.
+      def execute(data)
+        reset(data)
+        process
+      end
+
+      # Current options.
+      #
+      # @return [Hash]
+      #
+      def options
+        @data[:options]
+      end
+
+      # Current logger.
+      #
+      # @return [CloudApiLogger]
+      #
+      def cloud_api_logger
+        options[:cloud_api_logger]
+      end
+
+      # The method takes a block of code and logs how much time the given block took to execute.
+      #
+      # @param [String] description The prefix that is added to every logged line.
+      # @param [Symbol] log_key The log key (see {RightScale::CloudApi::CloudApiLogger}).
+      #
+      def with_timer(description = 'Timer', log_key = :timer, &block)
+        cloud_api_logger.log("#{description} started...",:timer)
+        start  = Time::now
+        result = block.call
+        cloud_api_logger.log("#{description} completed (#{'%.6f' % (Time::now - start)} sec)", log_key)
+        result
+      end
+      
+      # A helper method for invoking callbacks.
+      #
+      # The method checks if the given Proc exists and invokes it with the given set of arguments.
+      # In the case when proc==nil the method does nothing.
+      #
+      # @param [Proc] proc The callback.
+      # @param [Any] args A set of callback method arguments.
+      #
+      def invoke_callback_method(proc, *args) # :nodoc:
+        proc.call(*args) if proc.is_a?(Proc)
+      end
+    end
+    
+  end
+end

data/lib/right_cloud_api_base.rb

@@ -0,0 +1,72 @@
+#--
+# Copyright (c) 2013 RightScale, Inc.
+#
+# 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.
+#++
+
+require 'rubygems'
+require 'time'
+require 'openssl'
+require 'net/https'
+require 'base64'
+require 'cgi'
+require 'logger'
+require 'digest/md5'
+
+$:.unshift(File::expand_path(File::dirname(__FILE__)))
+
+require "right_cloud_api_base_version"
+
+# Helpers
+require "base/helpers/support"
+require "base/helpers/support.xml"
+require "base/helpers/utils"
+require "base/helpers/net_http_patch"
+require "base/helpers/http_headers"
+require "base/helpers/http_parent"
+require "base/helpers/http_request"
+require "base/helpers/http_response"
+require "base/helpers/query_api_patterns"
+require "base/helpers/cloud_api_logger"
+
+# Managers
+require "base/manager"
+require "base/api_manager"
+
+# Default parsers
+require "base/parsers/plain"
+require "base/parsers/json"
+require "base/parsers/rexml"
+require "base/parsers/sax"
+
+# Default routines
+require "base/routines/routine"
+require "base/routines/retry_manager"
+require "base/routines/request_initializer"
+require "base/routines/request_generator"
+require "base/routines/connection_proxy"
+require "base/routines/connection_proxies/right_http_connection_proxy"
+require "base/routines/connection_proxies/net_http_persistent_proxy"
+require "base/routines/response_parser"
+require "base/routines/request_analyzer"
+require "base/routines/response_analyzer"
+require "base/routines/cache_validator"
+require "base/routines/result_wrapper"
+

data/lib/right_cloud_api_base_version.rb

@@ -0,0 +1,37 @@
+#--
+# Copyright (c) 2013 RightScale, Inc.
+#
+# 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.
+#++
+
+# RightScale namespace
+#
+# @api public
+#
+module RightScale
+  # CloudApi gem namespace
+  module CloudApi
+    # CloudApi gem version namespace
+    module VERSION
+      # The gem version
+      STRING = '0.1.0'
+    end
+  end
+end

data/right_cloud_api_base.gemspec

@@ -0,0 +1,63 @@
+#--  -*- mode: ruby; encoding: utf-8 -*-
+# Copyright (c) 2013 RightScale, Inc.
+#
+# 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.
+#++
+
+require 'rubygems'
+require File.expand_path(File.join(File.dirname(__FILE__), 'lib/right_cloud_api_base_version'))
+
+Gem::Specification.new do |spec|
+  spec.name             = 'right_cloud_api_base'
+  spec.version          = RightScale::CloudApi::VERSION::STRING
+  spec.authors          = ['RightScale, Inc.']
+  spec.email            = 'support@rightscale.com'
+  spec.summary          = 'The gem provides base Query and REST API management functionalities for ' +
+                          'Amazon, OpenStack, Rackspace, CloudStack, etc cloud services'
+  spec.rdoc_options     = ['--main', 'README.md', '--title', '']
+  spec.extra_rdoc_files = ['README.md']
+  spec.require_path     = 'lib'
+  spec.required_ruby_version = '>= 1.8.7'
+
+  spec.add_dependency 'json',                  '>= 1.0.0'
+  spec.add_dependency 'ruby-hmac',             '>= 0.4.0'
+  spec.add_dependency 'libxml-ruby',           '>= 1.0.0'
+  spec.add_dependency 'net-http-persistent',   '>= 2.9.0'
+
+  spec.add_dependency 'redcarpet', (RUBY_VERSION < '1.9') ? '= 2.3.0' : '>= 3.0.0'
+
+  spec.add_development_dependency 'rspec',     '>= 2.14.0'
+  spec.add_development_dependency 'rake'
+
+  spec.description = <<-EOF
+== DESCRIPTION:
+
+right_cloud_api_base gem.
+
+The gem provides base Query and REST API management functionalities for
+Amazon, OpenStack, Rackspace, CloudStack, etc cloud services.
+
+EOF
+
+  candidates      = Dir.glob('{lib,spec}/**/*') +
+                    ['LICENSE', 'HISTORY', 'README.md', 'Rakefile', 'right_cloud_api_base.gemspec']
+  spec.files      = candidates.sort
+  spec.test_files = Dir.glob('spec/**/*')
+end