right_aws_api 0.1.0

data/lib/cloud/aws/base/manager.rb

@@ -0,0 +1,186 @@
+#--
+# 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 "cloud/aws/base/helpers/utils"
+require "cloud/aws/base/routines/request_signer"
+require "cloud/aws/base/parsers/response_error"
+
+
+module RightScale
+  module CloudApi
+
+    # AWS namespace
+    module AWS
+
+      # Thread safe parent class for almost all the AWS services.
+      class Manager < CloudApi::Manager
+      end
+
+      # Thread un-safe parent class for almost all the AWS services.
+      class ApiManager < CloudApi::ApiManager
+
+        # Standard AWS errors
+        class Error < CloudApi::Error
+        end
+
+        # A list of common AWS API params
+        COMMON_QUERY_PARAMS = [
+          'Action',
+          'AWSAccessKeyId',
+          'Expires',
+          'SecurityToken',
+          'Signature',
+          'SignatureMethod',
+          'SignatureVersion',
+          'Timestamp',
+          'Version',
+        ]
+
+        include Mixin::QueryApiPatterns
+
+        set_routine CloudApi::RetryManager
+        set_routine CloudApi::RequestInitializer
+        set_routine AWS::RequestSigner
+        set_routine CloudApi::RequestGenerator
+        set_routine CloudApi::RequestAnalyzer
+        set_routine CloudApi::ConnectionProxy
+        set_routine CloudApi::ResponseAnalyzer
+        set_routine CloudApi::CacheValidator
+        set_routine CloudApi::ResponseParser
+        set_routine CloudApi::ResultWrapper
+
+        set :response_error_parser => Parser::AWS::ResponseErrorV1
+
+        # Constructor
+        #
+        # @abstract
+        #
+        # @param [String] aws_access_key_id Amazon AWS access key id.
+        # @param [String] aws_secret_access_key Amazon secret AWS access key.
+        # @param [String] endpoint Cloud endpoint.
+        # @param [Hash]   options
+        #   see https://github.com/rightscale/right_cloud_api_base/blob/master/lib/base/api_manager.rb
+        #
+        # @example
+        #   new(key_id, secret, 'https://ec2.awsamazon.com', :cache => true)
+        #
+        def initialize(aws_access_key_id, aws_secret_access_key, endpoint, options={})
+          credentials = { :aws_access_key_id     => aws_access_key_id,
+                          :aws_secret_access_key => aws_secret_access_key }
+          super(credentials, endpoint, options)
+        end
+
+
+        # Makes a raw API call to AWS compatible service by the method name
+        #
+        # @param [String] action Depends on the selected service/endpoint.
+        #   See {http://aws.amazon.com/documentation/}
+        # @param [Hash] params A set or extra parameters.
+        # @option params [Hash,String] :body The request body.
+        # @option params [Hash] :headers The request headers.
+        # @option params [Hash] :options The request options (RightScale::CloudApi::ApiManager.process_api_request).
+        # @option params [Hash] :params The extra set of URL params.
+        #
+        # @return [Object] Usually a Hash with data.
+        #
+        # @example
+        #  ec2.api('DescribeImages')
+        #
+        # @example
+        #  ec2.api('DescribeInstances', 'InstanceId' => ['i-00000001', 'i-00000002'])
+        #
+        def api(action, params={}, &block)
+          params['Action'] ||= action.to_s._snake_case._camelize
+          opts = {}
+          opts[:body]    = params.delete(:body)
+          opts[:headers] = params.delete(:headers) || {}
+          opts[:options] = params.delete(:options) || {}
+          opts[:params]  = parametrize(params)
+          process_api_request(:get, '', opts, &block)
+        end
+
+
+        # Parametrize data to the format that Amazon EC2 and compatible services accept
+        #
+        # See {RightScale::CloudApi::Utils::AWS.parametrize} for more examples.
+        #
+        # @return [Hash] A hash of data in the format Amazon want to get.
+        #
+        # @example
+        #  parametrize( 'ParamA'             => 'a',
+        #               'ParamB'             => ['b', 'c'],
+        #               'ParamC.?.Something' => ['d', 'e'],
+        #               'Filter'             => [ { 'Key' => 'A', 'Value' => ['aa','ab']},
+        #                                         { 'Key' => 'B', 'Value' => ['ba','bb']}] ) #=>
+        #    {
+        #      "Filter.1.Key"       => "A",
+        #      "Filter.1.Value.1"   => "aa",
+        #      "Filter.1.Value.2"   => "ab",
+        #      "Filter.2.Key"       => "B",
+        #      "Filter.2.Value.1"   => "ba",
+        #      "Filter.2.Value.2"   => "bb",
+        #      "ParamA"             => "a",
+        #      "ParamB.1"           => "b",
+        #      "ParamB.2"           => "c",
+        #      "ParamC.1.Something" => "d",
+        #      "ParamC.2.Something" => "e"
+        #    }
+        #
+        def parametrize(*args)
+          Utils::AWS.parametrize(*args)
+        end
+
+
+        # @api public
+        alias_method :p9e, :parametrize
+
+
+        # Provides an ability to call methods by their API action names
+        #
+        # @param [String,Symbol] method_name
+        # @param [Objects] args
+        #
+        # @return [Object]
+        #
+        # @example
+        #  # the calls below produce the same result:
+        #  # way #1
+        #  ec2.api('DescribeInstances', 'InstanceId' => ['i-00000001', 'i-00000002'])
+        #  # way #2
+        #  ec2.DescribeInstances('InstanceId' => ['i-00000001', 'i-00000002'])
+        #
+        def method_missing(method_name, *args, &block)
+          begin
+            invoke_query_api_pattern_method(method_name, *args, &block)
+          rescue PatternNotFoundError
+            if method_name.to_s[/\A[A-Z]/]
+              api(method_name, *args, &block)
+            else
+              super
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cloud/aws/base/parsers/response_error.rb

@@ -0,0 +1,117 @@
+#--
+# 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
+    # Parsers namespace
+    module Parser
+      # AWS parsers namespace
+      module AWS
+
+        # AWS response error parser, case 1
+        #
+        class ResponseErrorV1
+
+          # Parse HTTP error message from a response body
+          #
+          # @param [RightScale::CloudApi::HTTPResponse] response
+          # @param [Hash] options
+          # @option options [Class] :xml_parser
+          #
+          # @return [String]
+          #
+          # @example
+          #  # For the call below:
+          #  ec2.DescribeInstances('InstanceId' => 'hohoho')
+          #  # Generates an XML error:
+          #  <?xml version="1.0" encoding="UTF-8"?>
+          #  <Response>
+          #    <Errors>
+          #      <Error>
+          #        <Code>InvalidInstanceID.Malformed</Code>
+          #        <Message>Invalid id: "hohoho"</Message>
+          #      </Error>
+          #    </Errors>
+          #    <RequestID>84bb3005-0b9f-4a1f-9f78-8fbc2a41a401</RequestID>
+          #  </Response>
+          #  # And the method parse all above into:
+          #  400: InvalidInstanceID.Malformed: Invalid id: "hohoho" (RequestID: 84bb3005-0b9f-4a1f-9f78-8fbc2a41a401)
+          #
+          def self.parse(response, options={})
+            result = "#{response.code}: "
+            body   = response.body.to_s
+            if response['content-type'].to_s[/xml/] || body[/\A<\?xml /]
+              hash = Utils::get_xml_parser_class(options[:xml_parser]).parse(body)
+              if hash["Response"] && hash["Response"]["Errors"]
+                errors = hash["Response"]["Errors"]["Error"]
+                errors = [ errors ] if errors.is_a?(Hash)
+                result += errors.map{ |error| "#{error['Code']}: #{error['Message']}" }.join('; ')
+                # Display a RequestId here
+                result << " (RequestID: #{hash["Response"]["RequestID"]})"
+              end
+            else
+              result << "#{body}" unless body._blank?
+            end
+            result
+          end
+        end
+
+        
+        # AWS response error parser, case 2
+        #
+        class ResponseErrorV2
+
+          # Parse HTTP error message from a response body
+          #
+          # @param [RightScale::CloudApi::HTTPResponse] response
+          # @param [Hash] options
+          # @option options [Class] :xml_parser
+          #
+          # @return a String to be displayed/logged.
+          #
+          # @example
+          #   # error is a response from ELB
+          #   parse(error) #=>
+          #     400: ErrorName: SomethingIsWrong (RequestID: 32455505-2345-43245-f432-34543523451)
+          # 
+          # @return [String]
+          #
+          def self.parse(response, options={})
+            result = "#{response.code}: "
+            body   = response.body.to_s
+            if response['content-type'].to_s[/xml/] || body[/\A<\?xml /]
+              hash = Utils::get_xml_parser_class(options[:xml_parser]).parse(body)
+              error = hash["ErrorResponse"] && hash["ErrorResponse"]["Error"]
+              if error
+                request_id = hash["ErrorResponse"]["RequestID"] || hash["ErrorResponse"]["RequestId"] 
+                result += "#{error['Type']}.#{error['Code']}: #{error['Message']} (RequestId: #{request_id})"
+              end
+            end
+            result
+          end
+        end
+        
+      end
+    end
+  end
+end

data/lib/cloud/aws/base/routines/request_signer.rb

@@ -0,0 +1,80 @@
+#--
+# 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
+    module AWS
+
+      # Request signer for AWS services.
+      class RequestSigner < CloudApi::Routine
+
+        # RequestSigner error
+        class Error < CloudApi::Error
+        end
+
+        # Use POST verb if GET's path is getting too big.
+        MAX_GET_REQUEST_PATH_LENGTH = 2000
+
+        # Authenticates an AWS request
+        #
+        # @return [void]
+        #
+        # @example
+        #  no example
+        #
+        def process
+          # Make sure all the required params are set
+          @data[:request][:params]['AWSAccessKeyId'] = @data[:credentials][:aws_access_key_id]
+          @data[:request][:params]['Version']      ||= @data[:options][:api_version]
+          # Compile a final request path
+          @data[:request][:path] = Utils::join_urn(@data[:connection][:uri].path, @data[:request][:relative_path])
+          # Sign the request
+          sign_proc = Proc::new do |data|
+            Utils::AWS::sign_v2_signature( data[:credentials][:aws_secret_access_key],
+                                           data[:request][:params] || {},
+                                           data[:request][:verb],
+                                           data[:connection][:uri].host,
+                                           data[:request][:path] )
+          end
+          signed_path = sign_proc.call(@data)
+          # Rebuild the request as POST if its path is too long
+          if signed_path.size > MAX_GET_REQUEST_PATH_LENGTH && @data[:request][:verb] == :get
+            @data[:request][:verb] = :post
+            signed_path = sign_proc.call(@data)
+          end
+          # Set new path or body and content-type
+          case @data[:request][:verb]
+          when :get
+            @data[:request][:path] << "?#{signed_path}"
+          when :post
+            @data[:request][:body] = signed_path
+            @data[:request][:headers]['content-type'] = 'application/x-www-form-urlencoded; charset=utf-8'
+          else
+            fail Error::new("Unsupported HTTP verb: #{@data[:request][:verb]}")
+          end
+        end
+      end
+        
+    end
+  end
+end

data/lib/cloud/aws/cf/manager.rb

@@ -0,0 +1,171 @@
+#--
+# 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 "cloud/aws/base/helpers/utils"
+require "cloud/aws/base/parsers/response_error"
+require "cloud/aws/cf/routines/request_signer"
+require "cloud/aws/cf/wrappers/default"
+
+module RightScale
+  module CloudApi
+    module AWS
+
+      # Cloud Front namespace
+      #
+      # @api public
+      #
+      module CF
+
+        # Amazon Cloud Front (CF) compatible manager (thread safe)
+        #
+        # @example
+        #  require "right_aws_api"
+        #
+        #  cf = RightScale::CloudApi::AWS::CF::Manager::new(key, secret, 'https://cloudfront.amazonaws.com')
+        #
+        #  cf.GetDistributionList('MaxItems' => 2) #=>
+        #    {"DistributionList"=>
+        #      {"IsTruncated"=>"true",
+        #       "NextMarker"=>"E20O0ZWO4WRF3I",
+        #       "Marker"=>nil,
+        #       "MaxItems"=>"2",
+        #       "DistributionSummary"=>
+        #        [{"Status"=>"Deployed",
+        #          "Comment"=>"test",
+        #          "Enabled"=>"true",
+        #          "LastModifiedTime"=>"2008-10-23T15:17:24.447Z",
+        #          "CNAME"=>["c1.test.com", "c2.test.com"],
+        #          "Id"=>"E2FLHADADBK2P9",
+        #          "DomainName"=>"d2kia27jveea52.cloudfront.net",
+        #          "S3Origin"=>{"DNSName"=>"aws-test.s3.amazonaws.com"}},
+        #         {"Status"=>"Deployed",
+        #          "Comment"=>
+        #           "Distribution created for the blog demo, can be deleted anytime.",
+        #          "Enabled"=>"false",
+        #          "LastModifiedTime"=>"2009-04-20T07:05:37.257Z",
+        #          "CNAME"=>"blog-demo.rightscale.com",
+        #          "Id"=>"E20O0ZWO4WRF3I",
+        #          "DomainName"=>"dc5eg4un365fp.cloudfront.net",
+        #          "S3Origin"=>{"DNSName"=>"aws-test.s3.amazonaws.com"}}],
+        #       "@xmlns"=>"http://cloudfront.amazonaws.com/doc/2010-11-01/"}}
+        #
+        # @example
+        #  cf.GetDistribution('DistributionId' => 'E2FLHADADBK2P9') #=> 
+        #    {"Distribution"=>
+        #        {"Status"=>"Deployed",
+        #        "LastModifiedTime"=>"2008-10-23T15:17:24.447Z",
+        #        "InProgressInvalidationBatches"=>"0",
+        #        "Id"=>"E2FLHADADBK2P9",
+        #        "DistributionConfig"=>
+        #          {"Comment"=>"test",
+        #          "Enabled"=>"true",
+        #          "CallerReference"=>"200810231517246798821075",
+        #          "CNAME"=>["c1.test.com", "c2.test.com"],
+        #          "S3Origin"=>{"DNSName"=>"aws-test.s3.amazonaws.com"}},
+        #        "DomainName"=>"d2kia27jveea52.cloudfront.net",
+        #        "@xmlns"=>"http://cloudfront.amazonaws.com/doc/2010-11-01/"}}
+        #
+        # @see ApiManager
+        # @see Wrapper::DEFAULT.extended Wrapper::DEFAULT.extended (click [View source])
+        # @see http://docs.aws.amazon.com/AmazonCloudFront/latest/APIReference/Welcome.html
+        #
+        class Manager < CloudApi::Manager
+        end
+
+        # Amazon Cloud Front (CF) compatible manager (thread unsafe)
+        #
+        # @see Manager
+        #
+        class  ApiManager < CloudApi::ApiManager
+
+          # CF Error
+          class Error < CloudApi::Error
+          end
+
+          # Default API version for CloudFront service
+          #
+          # To override the API version use :api_version key when instantiating a manager.
+          #
+          DEFAULT_API_VERSION = '2012-07-01'
+
+          include Mixin::QueryApiPatterns
+
+          set_routine CloudApi::RetryManager
+          set_routine CloudApi::RequestInitializer
+          set_routine AWS::CF::RequestSigner
+          set_routine CloudApi::RequestGenerator
+          set_routine CloudApi::ConnectionProxy
+          set_routine CloudApi::ResponseAnalyzer
+          set_routine CloudApi::ResponseParser
+          set_routine CloudApi::ResultWrapper
+
+          set :response_error_parser => Parser::AWS::ResponseErrorV2
+
+
+          # Initializes Amazon CloudFront service manager
+          #
+          # @param [String] aws_access_key_id
+          # @param [String] aws_secret_access_key
+          # @param [String] endpoint
+          # @param [Hash]   options
+          #
+          # @return [RightScale::CloudApi::AWS::CF::ApiManager]
+          #
+          # @example
+          #   # see Manager class for example
+          #
+          # @see Manager
+          #
+          def initialize(aws_access_key_id, aws_secret_access_key, endpoint, options={})
+            credentials = { :aws_access_key_id     => aws_access_key_id,
+                            :aws_secret_access_key => aws_secret_access_key }
+            super(credentials, endpoint, options)
+          end
+
+
+          # Makes an API call to AWS Cloud Front compatible cloud
+          #
+          # @param [String,Symbol] verb
+          # @param [Objects] args
+          #
+          # @return [Object]
+          #
+          # @example
+          #   api(verb,                      opts={})
+          #   api(verb, 'distribution',      opts={})
+          #   # Where opts may have next keys: :options, :headers, :params
+          #   api(verb, 'distribution/path', opts={})
+          #
+          def api(verb, *args, &block)
+            relative_path = args.first.is_a?(String) ? args.shift : ''
+            opts          = args.shift || {}
+            raise Error::new("Opts must be Hash not #{opts.class.name}") unless opts.is_a?(Hash)
+            process_api_request(verb, relative_path, opts, &block)
+          end
+                    
+        end
+
+      end
+    end
+  end
+end