simple_aws 0.0.1a

data/.gitignore

@@ -0,0 +1,4 @@
+Gemfile.lock
+doc
+pkg
+.bundle

data/.travis.yml

@@ -0,0 +1,8 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - rbx
+  - ruby-head
+  - ree
+  - jruby

data/Gemfile

@@ -0,0 +1,12 @@
+source :rubygems
+
+gemspec
+
+group :development do
+  gem "rake"
+end
+
+group :test do
+  gem "minitest", :require => false
+  gem "mocha", :require => false
+end

data/README.md

@@ -0,0 +1,73 @@
+SimpleAWS
+=========
+
+A thin, simple, forward compatible Ruby wrapper around the various Amazon AWS API.
+
+What? Why?!
+-----------
+
+Another Ruby library to talk to Amazon Web Services? Why don't you just use fog
+or aws or aws-sdk or right_aws or any of the myriad of others already in existence?
+Why are you creating yet another one?
+
+There's a simple, two part answer to this:
+
+### Complexity
+
+It's in the name. *Simple* AWS. This library focuses on being the simplest possible way
+to communicate with AWS. There's been a growing trend in the Ruby Library scene to abstract
+and wrap everything possible in ActiveRecord-like objects so the library user doesn't
+have to worry about the details of sending requests and parsing responses from AWS.
+Some make it harder than others to get to the raw requests, but once down there you
+run into the other problem these libraries have.
+
+### Forward Compatibility
+
+Yes, not Backward, *Forward* compatibility. SimpleAWS is completely forward compatible to
+any changes AWS makes to it's various APIs. It's well known that Amazon's AWS
+is constantly changing, constantly being updated and added to. Unfortunately, there isn't
+a library out there that lives this truth. Either parameters are hard coded, or response
+values are hard coded, and for all of them the requests themselves are hard built into
+the libraries, making it very hard to work with new API requests.
+
+It's time for a library that evolves with Amazon AWS automatically and refuses to
+get in your way. AWS's API is extremely well documented, consistent, and clean. The libraries
+we use to interact with the API should match these truths as well.
+
+How Simple?
+-----------
+
+Open a connection to the interface you want to talk to, and start calling methods.
+
+```ruby
+ec2 = AWS::EC2.new(key, secret)
+response = ec2.describe_instances
+```
+
+If this looks familiar to other libraries, well, it's hard to get much simpler than this. Once
+you move past no parameter methods though, the differences abound. What happens when Amazon
+adds another parameter to DescribeInstances? SimpleAWS doesn't care, just start using it.
+
+SimpleAWS is as light of a Ruby wrapper around the AWS APIs as possible. There are no
+hard-coded parameters, no defined response types, you work directly with what the AWS
+API says you get.
+
+What SimpleAWS does do is to hide the communication complexities, the XML parsing, and
+if you want to use it, some of the odd parameter systems AWS uses (PublicIp.n and the like).
+On top of this, SimpleAWS works to ensure everything possible is as Ruby as possible. Methods
+are underscore, the Response object can be queried using methods or a hash structure, and
+parameter keys are converted to CamelCase strings as needed.
+
+You're trying to use Amazon AWS, don't let libraries get in your way.
+
+Project Info
+------------
+
+Author: Jason Roelofs (https://github.com/jameskilton)
+
+Source: https://github.com/jameskilton/simple_aws
+
+Issues: https://github.com/jameskilton/simple_aws/issues
+
+[![Travis CI Build Status](https://secure.travis-ci.org/jameskilton/simple_aws.png)](http://travis-ci.org/jameskilton/simple_aws)
+

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+
+task :default => :test
+
+desc "Run all tests"
+Rake::TestTask.new(:test) do |t|
+  t.pattern = "test/**/*_test.rb"
+  t.libs = ["lib", "test"]
+end

data/lib/aws/api.rb

@@ -0,0 +1,82 @@
+require 'aws/core/util'
+require 'aws/core/connection'
+require 'aws/core/request'
+
+module AWS
+
+  ##
+  # Base class for all endpoint handler classes.
+  #
+  # See the list of AWS Endpoints for the values to use when
+  # implementing various APIs:
+  #
+  #   http://docs.amazonwebservices.com/general/latest/gr/index.html?rande.html
+  ##
+  class API
+    class << self
+
+      ##
+      # Define the AWS endpoint for the API being wrapped.
+      ##
+      def endpoint(endpoint)
+        @endpoint = endpoint
+      end
+
+      ##
+      # Specify a default region for all requests for this API.
+      # This region will be used if no region is given to the
+      # constructor
+      ##
+      def default_region(region)
+        @default_region = region
+      end
+
+      ##
+      # Specify whether this API uses HTTPS for requests. If not set,
+      # the system will use HTTP. Some API endpoints are not available under
+      # HTTP and some are only HTTP.
+      ##
+      def use_https(value)
+        @use_https = value
+      end
+
+      ##
+      # Specify the AWS version of the API in question. This will be a date string.
+      ##
+      def version(version)
+        @version = version
+      end
+
+    end
+
+    attr_reader :access_key, :secret_key, :region, :version
+
+    ##
+    # Construct a new access object for the API in question.
+    # +access_key+ and +secret_key+ are as defined in AWS security standards.
+    # Use +region+ if you need to explicitly talk to a certain AWS region
+    ##
+    def initialize(access_key, secret_key, region = nil)
+      @access_key = access_key
+      @secret_key = secret_key
+
+      @region = region || self.class.instance_variable_get("@default_region")
+      @endpoint = self.class.instance_variable_get("@endpoint")
+      @use_https = self.class.instance_variable_get("@use_https")
+      @version = self.class.instance_variable_get("@version")
+    end
+
+    ##
+    # Get the full host name for the current API
+    ##
+    def uri
+      return @uri if @uri
+
+      @uri = @use_https ? "https" : "http"
+      @uri += "://#{@endpoint}"
+      @uri += ".#{@region}" if @region
+      @uri += ".amazonaws.com"
+      @uri
+    end
+  end
+end

data/lib/aws/call_types/action_param.rb

@@ -0,0 +1,68 @@
+require 'aws/core/util'
+require 'aws/core/request'
+require 'aws/core/connection'
+
+module AWS
+  module CallTypes
+
+    ##
+    # Implement call handling to work with the ?Action param, signing the message
+    # according to that which is defined in EC2 and ELB.
+    ##
+    module ActionParam
+      ##
+      # For any undefined methods, try to convert them into valid AWS
+      # actions and return the results
+      ##
+      def method_missing(name, *args)
+        request = AWS::Request.new :post, self.uri, "/"
+        request.params["Action"] = AWS::Util.camelcase(name.to_s)
+
+        if args.any? && args.first.is_a?(Hash)
+          args.first.each do |key, value|
+            request.params[key] = value
+          end
+        end
+
+        connection = AWS::Connection.new
+        connection.call finish_and_sign_request(request)
+      end
+
+      protected
+
+      ##
+      # Build and sign the final request, as per the rules here:
+      # http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/index.html?using-query-api.html
+      ##
+      def finish_and_sign_request(request)
+        request.params.merge!({
+          "AWSAccessKeyId" => self.access_key,
+          "SignatureMethod" => "HmacSHA256",
+          "SignatureVersion" => "2",
+          "Timestamp" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+          "Version" => self.version
+        })
+
+        request.params["Signature"] = Base64.encode64(sign_request(request.params.clone)).chomp
+
+        request
+      end
+
+      def sign_request(params)
+        list = params.map {|k, v| [k, Util.uri_escape(v.to_s)] }
+        list.sort! do |a, b|
+          if a[0] == "AWSAccessKeyId"
+            -1
+          else
+            a[0] <=> b[0]
+          end
+        end
+
+        host = self.uri.gsub(/^http[s]:\/\//,'')
+
+        to_sign = "POST\n#{host}\n/\n#{list.map {|p| p.join("=") }.join("&")}"
+        OpenSSL::HMAC.digest("sha256", self.secret_key, to_sign)
+      end
+    end
+  end
+end

data/lib/aws/core/connection.rb

@@ -0,0 +1,32 @@
+require 'httparty'
+require 'openssl'
+
+require 'aws/core/response'
+
+module AWS
+
+  class HTTP
+    include HTTParty
+    format :xml
+  end
+
+  ##
+  # Handles all communication to and from AWS itself
+  ##
+  class Connection
+
+    ##
+    # Send an AWS::Request to AWS proper, returning an AWS::Response.
+    # Will raise if the request has an error
+    ##
+    def call(request)
+      AWS::Response.new(
+        HTTP.send(request.method,
+          request.uri,
+          :query => request.params
+        )
+      )
+    end
+
+  end
+end

data/lib/aws/core/request.rb

@@ -0,0 +1,133 @@
+module AWS
+
+  ##
+  # Defines all request information needed to run a request against an AWS API
+  #
+  # Requests need to know a number of attributes to work, including the host,
+  # path, the HTTP method, and any params or POST bodies. Most of this is
+  # straight forward through the constructor and setter methods defined below.
+  #
+  # One of the more interesting aspects of the AWS API are the indexed parameters.
+  # These are the parameters in the document defined as such:
+  #
+  #   Filter.n.Name
+  #   Filter.n.Value.m
+  #
+  # This class has special handling to facilitate building these parameters
+  # from regular Ruby Hashes and Arrays, but does not prevent you from specifying
+  # these parameters exactly as defined. For the example above, here are the two
+  # ways you can set these parameters:
+  #
+  # By yourself, filling in the +n+ and +m+ as you need:
+  #
+  #   request.params.merge({
+  #     "Filter.1.Name" => "domain",
+  #     "Filter.1.Value" => "vpc",
+  #     "Filter.2.Name" => "ids",
+  #     "Filter.2.Value.1" => "i-1234",
+  #     "Filter.2.Value.2" => "i-8902"
+  #   })
+  #
+  # Or let Request handle the indexing and numbering for you:
+  #
+  #   request.params["Filter"] = [
+  #     {"Name" => "domain", "Value" => "vpc"},
+  #     {"Name" => "ids", "Value" => ["i-1234", "i-8902"]}
+  #   ]
+  #
+  # If you have just a single Filter, you don't need to wrap it in an array,
+  # Request will do that for you:
+  #
+  #   request.params["Filter"] = {"Name" => "domain", "Value" => "vpc"}
+  #
+  # Straight arrays are handled as well:
+  #
+  #   request.params["InstanceId"] = ["i-1234", "i-8970"]
+  #
+  # In an effort to make this library as transparent as possible when working
+  # directly with the AWS API, the keys of the hashes must be the values
+  # specified in the API, and the values must be Hashes, Arrays, or serializable
+  # values like Fixnum, Boolean, or String.
+  #
+  # A more detailed example can be found in test/aws/request_test.rb where you'll
+  # see how to use many levels of nesting to build your AWS request.
+  ##
+  class Request
+
+    class Params < Hash
+
+      def []=(key, value)
+        case value
+        when Array
+          process_array key, value
+        when Hash
+          process_array key, [value]
+        else
+          super
+        end
+      end
+
+      protected
+
+      def process_array(base_key, array_in)
+        array_in.each_with_index do |entry, index|
+          entry_key = "#{base_key}.#{index + 1}"
+          case entry
+          when Hash
+            process_hash entry_key, entry
+          else
+            self[entry_key] = entry
+          end
+        end
+      end
+
+      def process_hash(base_key, entry)
+        entry.each do |inner_key, inner_value|
+          full_inner_key = "#{base_key}.#{inner_key}"
+          case inner_value
+          when Array
+            process_array full_inner_key, inner_value
+          else
+            self[full_inner_key] = inner_value
+          end
+        end
+      end
+
+    end
+
+    ##
+    # HTTP method this Request will use (:get, :post, :put, :delete)
+    ##
+    attr_reader :method
+
+    ##
+    # Host and Path of the URI this Request will be using
+    ##
+    attr_reader :host, :path
+
+    ##
+    # Hash of parameters to pass in this Request. See top-level
+    # documentation for any special handling of types
+    ##
+    attr_reader :params
+
+    ##
+    # Set up a new Request for the given +host+ and +path+ using the given
+    # http +method+ (:get, :post, :put, :delete).
+    ##
+    def initialize(method, host, path)
+      @method = method
+      @host = host
+      @path = path
+      @params = Params.new
+    end
+
+    ##
+    # Build up the full URI
+    ##
+    def uri
+      "#{host}#{path}"
+    end
+
+  end
+end

data/lib/aws/core/response.rb

@@ -0,0 +1,231 @@
+require 'aws/core/util'
+
+module AWS
+
+  class UnsuccessfulResponse < RuntimeError
+    attr_reader :code
+    attr_reader :error_type
+    attr_reader :error_message
+
+    def initialize(code, error_type, error_message)
+      super "#{error_type} (#{code}): #{error_message}"
+      @code = code
+      @error_type = error_type
+      @error_message = error_message
+    end
+  end
+
+  class UnknownErrorResponse < RuntimeError
+    def initialize(body)
+      super "Unable to parse error code from #{body.inspect}"
+    end
+  end
+
+  ##
+  # Wrapper object for all responses from AWS. This class gives
+  # a lot of leeway to how you access the response object.
+  # You can access the response directly through it's Hash representation,
+  # which is a direct mapping from the raw XML returned from AWS.
+  #
+  # You can also use ruby methods. This object will convert those methods
+  # in ruby_standard into appropriate keys (camelCase) and look for them
+  # in the hash. This can be done at any depth.
+  #
+  # This class tries not to be too magical to ensure that
+  # it never gets in the way. All nested objects are queryable like their
+  # parents are, and all sets and arrays are found and accessible through
+  # your typical Enumerable interface.
+  #
+  # The starting point of the Response querying will vary according to the structure
+  # returned by the AWS API in question. For some APIs, like EC2, the response is
+  # a relatively flat:
+  #
+  #  <DataRequestResponse>
+  #    <requestId>...</requestId>
+  #    <dataRequested>
+  #      ...
+  #    </dataRequested>
+  #  </DataRequestResponse>
+  #
+  # In this case, your querying will start inside of <DataRequestResponse>, ala the first
+  # method you'll probably call is +data_requested+. For other APIs, the response
+  # object is a little deeper and looks like this:
+  #
+  #  <DataRequestResponse>
+  #    <DataRequestedResult>
+  #       <DataRequested>
+  #          ...
+  #       </DataRequested>
+  #    </DataRequestedResult>
+  #    <ResponseMetadata>
+  #      <RequestId>...</RequestId>
+  #    </ResponseMetadata>
+  #  </DataRequestResponse>
+  #
+  # For these response structures, your query will start inside of <DataRequestedResult>,
+  # ala your first method call will be +data_requested+. To get access to the request id of
+  # both of these structures, simply use #request_id on the base response. You'll also
+  # notice the case differences of the XML tags, this class tries to ensure that case doesn't
+  # matter when you're querying with methods. If you're using raw hash access then yes the
+  # case of the keys in question need to match.
+  #
+  # This class does ensure that any collection is always an Array, given that
+  # when AWS returns a single item in a collection, the xml -> hash parser gives a
+  # single hash back instead of an array. This class will also look for
+  # array indicators from AWS, like <item> or <member> and squash them.
+  #
+  # If AWS returns an error code, instead of getting a Response back the library
+  # will instead throw an UnsuccessfulResponse error with the pertinent information.
+  ##
+  class Response
+
+    # Inner proxy class that handles converting ruby methods
+    # into keys found in the underlying Hash.
+    class ResponseProxy
+      include Enumerable
+
+      TO_SQUASH = %w(item member)
+
+      def initialize(local_root)
+        first_key = local_root.keys.first
+        if local_root.keys.length == 1 && TO_SQUASH.include?(first_key)
+          # Ensure squash key is ignored and it's children are always
+          # turned into an array.
+          @local_root = [local_root[first_key]].flatten.map do |entry|
+            ResponseProxy.new entry
+          end
+        else
+          @local_root = local_root
+        end
+      end
+
+      def [](key_or_idx)
+        value_or_proxy @local_root[key_or_idx]
+      end
+
+      ##
+      # Get all keys at the current depth of the Response object.
+      # This method will raise a NoMethodError if the current
+      # depth is an array.
+      ##
+      def keys
+        @local_root.keys
+      end
+
+      def length
+        @local_root.length
+      end
+
+      def each(&block)
+        @local_root.each(&block)
+      end
+
+      def method_missing(name, *args)
+        if key = key_matching(name)
+          value_or_proxy @local_root[key]
+        else
+          super
+        end
+      end
+
+      protected
+
+      def key_matching(name)
+        return nil if @local_root.is_a? Array
+
+        lower_base_aws_name = AWS::Util.camelcase name.to_s, :lower
+        upper_base_aws_name = AWS::Util.camelcase name.to_s
+
+        keys = @local_root.keys
+
+        if keys.include? lower_base_aws_name
+          lower_base_aws_name
+        elsif keys.include? upper_base_aws_name
+          upper_base_aws_name
+        end
+      end
+
+      def value_or_proxy(value)
+        if value.is_a?(Hash) || value.is_a?(Array)
+          ResponseProxy.new value
+        else
+          value
+        end
+      end
+    end
+
+    ##
+    # The raw parsed response body in Hash format
+    ##
+    attr_reader :body
+
+    def initialize(http_response)
+      if !http_response.success?
+        error = parse_error_from http_response.parsed_response
+        raise UnsuccessfulResponse.new(
+          http_response.code,
+          error["Code"],
+          error["Message"]
+        )
+      end
+
+      @body = http_response.parsed_response
+
+      inner = @body[@body.keys.first]
+      response_root =
+        if result_key = inner.keys.find {|k| k =~ /Result$/}
+          inner[result_key]
+        else
+          inner
+        end
+
+      @request_root = ResponseProxy.new response_root
+    end
+
+    ##
+    # Direct access to the request body's hash.
+    # This works on the first level down in the AWS response, bypassing
+    # the root element of the returned XML so you can work directly in the
+    # attributes that matter
+    ##
+    def [](key)
+      @request_root[key]
+    end
+
+    ##
+    # Delegate first-level method calls to the root Proxy object
+    ##
+    def method_missing(name, *args)
+      @request_root.send(name, *args)
+    end
+
+    ##
+    # Get the request ID from this response. Works on all known AWS response formats.
+    # Some AWS APIs don't give a request id, such as CloudFront. For responses that
+    # do not have a request id, this method returns nil.
+    ##
+    def request_id
+      if metadata = @body[@body.keys.first]["ResponseMetadata"]
+        metadata["RequestId"]
+      elsif id = @body[@body.keys.first]["requestId"]
+        id
+      else
+        nil
+      end
+    end
+
+    protected
+
+    def parse_error_from(body)
+      if body.has_key? "ErrorResponse"
+        body["ErrorResponse"]["Error"]
+      elsif body.has_key? "Response"
+        body["Response"]["Errors"]["Error"]
+      else
+        raise UnknownErrorResponse.new body
+      end
+    end
+
+  end
+
+end

data/lib/aws/core/util.rb

@@ -0,0 +1,32 @@
+module AWS
+  ##
+  # Collection of helper methods used in the library
+  ##
+  module Util
+
+    ##
+    # Simpler version of ActiveSupport's camelize
+    ##
+    def self.camelcase(string, lower_first_char = false)
+      if lower_first_char
+        string[0,1].downcase + camelcase(string)[1..-1]
+      else
+        string.split(/_/).map{ |word| word.capitalize }.join('')
+      end
+    end
+
+
+    # AWS URI escaping, as implemented by Fog
+    def self.uri_escape(string)
+      # Quick hack for already escaped string, don't escape again
+      # I don't think any requests require a % in a parameter, but if
+      # there is one I'll need to rethink this
+      return string if string =~ /%/
+
+      string.gsub(/([^a-zA-Z0-9_.\-~]+)/) {
+        "%" + $1.unpack("H2" * $1.bytesize).join("%").upcase
+      }
+    end
+
+  end
+end