aws-sdk 1.0.0

data/lib/aws/cacheable.rb

@@ -0,0 +1,92 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/naming'
+require 'aws/meta_utils'
+
+module AWS
+
+  # @private
+  module Cacheable
+
+    def local_cache_key
+      raise NotImplementedError
+    end
+
+    def cache_key
+      endpoint_method = self.class.service_ruby_name + "_endpoint"
+      config.signer.access_key_id + ":" +
+        config.send(endpoint_method) + ":" +
+        local_cache_key
+    end
+
+    def attributes_from_response(response)
+      method = "populate_from_#{response.request_type}"
+      if respond_to?(method)
+        send(method, response)
+      end
+    end
+
+    def request_types
+      self.class.request_types
+    end
+
+    class NoData < StandardError; end
+
+    def retrieve_attribute(attribute)
+      if cache = AWS.response_cache
+        if cache.resource_cache.cached?(cache_key, attribute)
+          return cache.resource_cache.get(cache_key, attribute)
+        end
+        cache.select(*request_types).each do |resp|
+          if attributes = attributes_from_response(resp)
+            cache.resource_cache.store(cache_key, attributes)
+            return attributes[attribute] if attributes.key?(attribute)
+          end
+        end
+      end
+      resp = yield
+      if attributes = attributes_from_response(resp)
+        if cache = AWS.response_cache
+          cache.resource_cache.store(cache_key, attributes)
+        end
+        attributes[attribute] if attributes.key?(attribute)
+      else
+        raise NoData.new("no data for #{self} in response to #{resp.request_type}")
+      end
+    end
+
+    module ClassMethods
+
+      def request_types
+        []
+      end
+
+      def populate_from(type, &block)
+        define_method("populate_from_#{type}", &block)
+        new_request_types = request_types + [type]
+        new_request_types.uniq!
+        MetaUtils.extend_method(self, :request_types) { new_request_types }
+      end
+
+    end
+
+    def self.included(mod)
+      mod.extend ClassMethods
+      mod.extend Naming unless
+        mod.respond_to?(:service_ruby_name)
+    end
+
+  end
+
+end

data/lib/aws/common.rb

@@ -0,0 +1,228 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/configuration'
+require 'aws/resource_cache'
+require 'aws/response_cache'
+
+# Root namespace for the AWS SDK for Ruby.
+module AWS
+  class << self
+
+    # @private
+    @@config = nil
+
+    # The global configuration for AWS.  Generally you set your prefered
+    # configuration operations once after loading the aws-sdk gem.  
+    #
+    #   AWS.config({
+    #     :access_key_id => 'ACCESS_KEY_ID',
+    #     :secret_access_key => 'SECRET_ACCESS_KEY',
+    #     :simple_db_endpoint => 'sdb.us-west-1.amazonaws.com',
+    #     :max_retries => 2,
+    #   })
+    #
+    # When using AWS classes they will always default to use configuration
+    # values defined in {AWS.config}.
+    #
+    #   AWS.config(:max_retries => 2)
+    #
+    #   sqs = AWS::SQS.new
+    #   sqs.config.max_retries #=> 2
+    #
+    # If you want to change a configuration value for a single instance you
+    # pass the new configuration value to that objects initializer:
+    #
+    #   AWS::SQS.new(:max_retries => 0)
+    #
+    # @note Changing the global configuration does not affect objects
+    #   that have already been constructed.
+    # @param [Hash] options
+    # @option options [String] :access_key_id Your account access key 
+    #   id credential.
+    # @option options [String] :secret_access_key Your account secret
+    #   access key credential.
+    # @option options [Integer] :max_retries (3) The maximum number of times
+    #   service errors (500) should be retried.  There is an exponential 
+    #   backoff in between service request retries, so the more retries the
+    #   longer it can take to fail.
+    # @option options [String] :ec2_endpoint ('ec2.amazonaws.com') The
+    #   service endpoint to use when communicating with Amazon EC2.
+    # @option options :http_handler The request/response handler
+    #   for all service requests.  The default handler uses HTTParty to
+    #   send requests.
+    # @option options :logger (nil) A logger instance that should receive log
+    #   messages generated by service requets.  A logger needs to respond to
+    #   #log and must accept a severity (e.g. :info, :error, etc) and
+    #   a string message.
+    # @option options [String] :s3_endpoint ('s3.amazonaws.com') The
+    #   service endpoint to use when communicating with Amazon S3.
+    # @option [Integer] :s3_multipart_threshold (16777216) When uploading
+    #   data to S3, if the number of bytes to send exceedes 
+    #   +:s3_multipart_threshold+ then a multi part session is automatically
+    #   started and the data is sent up in chunks.  The size of each part
+    #   is specified by +:s3_multipart_min_part_size+.
+    # @option [Integer] :s3_multipart_min_part_size (5242880) 
+    # @option [Integer] :s3_multipart_max_parts (1000)
+    # @option options [Boolean] :simple_db_consistent_reads (false) When true
+    #   all read operations against SimpleDB will be consistent reads (slower).
+    # @option options [String] :simple_db_endpoint ('sdb.amazonaws.com') The
+    #   service endpoint to use when communicating with Amazon SimpleDB.
+    # @option options [String] :simple_email_service_endpoint ('email.us-east-1.amazonaws.com')
+    #   The service endpoint to use when communicating with Amazon 
+    #   SimpleEmailService.
+    # @option options :signer The request signer.  Defaults to a
+    #   {DefaultSigner}.
+    # @option options [String] :sns_endpoint ('sns.us-east-1.amazonaws.com') 
+    #   The service endpoint to use when communicating with Amazon SNS.
+    # @option options [String] :sqs_endpoint ('sqs.us-east-1.amazonaws.com') 
+    #   The service endpoint to use when communicating with Amazon SQS.
+    # @option options :stub_requests (false) When true no requests will be
+    #   made against the live service.  Responses returned will have empty
+    #   values. This is primarily used for writing tests.
+    # @option options [Boolean] :use_ssl (true) When true, all requests are
+    #   sent over SSL.
+    # @option options [String] :user_agent_prefix (nil) A string prefix to 
+    #   append to all requets against AWS services.  This should be set
+    #   for clients and applications built ontop of the aws-sdk gem.
+    # @return [Configuration] Returns the new configuration.
+    def config options = {}
+      @@config ||= Configuration.new
+      @@config = @@config.with(options) unless options.empty?
+      @@config
+    end
+
+    # @note Memoization is currently only supported for the EC2 APIs;
+    #   other APIs are unaffected by the status of memoization.  To
+    #   protect your code from future changes in memoization support,
+    #   you should not enable memoization while calling non-EC2 APIs.
+    #
+    # Starts memoizing service requests made in the current thread.
+    # See {memoize} for a full discussion of the memoization feature.
+    # This has no effect if memoization is already enabled.
+    def start_memoizing
+      Thread.current[:aws_memoization] ||= {}
+      nil
+    end
+
+    # @note Memoization is currently only supported for the EC2 APIs;
+    #   other APIs are unaffected by the status of memoization.  To
+    #   protect your code from future changes in memoization support,
+    #   you should not enable memoization while calling non-EC2 APIs.
+    #
+    # Stops memoizing service requests made in the current thread.
+    # See {memoize} for a full discussion of the memoization feature.
+    # This has no effect if memoization is already disabled.
+    def stop_memoizing
+      Thread.current[:aws_memoization] = nil
+    end
+
+    # @note Memoization is currently only supported for the EC2 APIs;
+    #   other APIs are unaffected by the status of memoization.  To
+    #   protect your code from future changes in memoization support,
+    #   you should not enable memoization while calling non-EC2 APIs.
+    #
+    # @return [Boolean] True if memoization is enabled for the current
+    #   thread.  See {memoize} for a full discussion of the
+    #   memoization feature.
+    def memoizing?
+      !Thread.current[:aws_memoization].nil?
+    end
+
+    # @note Memoization is currently only supported for the EC2 APIs;
+    #   other APIs are unaffected by the status of memoization.  To
+    #   protect your code from future changes in memoization support,
+    #   you should not enable memoization while calling non-EC2 APIs.
+    #
+    # Enables memoization for the current thread, within a block.
+    # Memoization lets you avoid making multiple requests for the same
+    # data by reusing the responses which have already been received.
+    # For example, consider the following code to get the most
+    # recently launched EC2 instance:
+    #
+    #  latest = ec2.instances.sort_by(&:launch_time).last
+    #
+    # The above code would make N+1 requests (where N is the number of
+    # instances in the account); iterating the collection of instances
+    # is one request, and +Enumerable#sort_by+ calls
+    # {AWS::EC2::Instance#launch_time} for each instance, causing
+    # another request per instance.  We can rewrite the code as
+    # follows to make only one request:
+    #
+    #  latest = AWS.memoize do
+    #    ec2.instances.sort_by(&:launch_time).last
+    #  end
+    #
+    # Iterating the collection still causes a request, but each
+    # subsequent call to {AWS::EC2::Instance#launch_time} uses the
+    # results from that first request rather than making a new request
+    # for the same data.
+    #
+    # While memoization is enabled, every response that is received
+    # from the service is retained in memory.  Therefore you should
+    # use memoization only for short-lived blocks of code that make
+    # relatively small numbers of requests.  The cached responses are
+    # used in two ways while memoization is enabled:
+    #
+    # 1. Before making a request, the SDK checks the cache for a
+    #    response to a request with the same signature (credentials,
+    #    service endpoint, operation name, and parameters).  If such a
+    #    response is found, it is used instead of making a new
+    #    request.
+    #
+    # 2. Before retrieving data for an attribute of a resource
+    #    (e.g. {AWS::EC2::Instance#launch_time}), the SDK attempts to
+    #    find a cached response that contains the requested data.  If
+    #    such a response is found, the cached data is returned instead
+    #    of making a new request.
+    #
+    # When memoization is disabled, all previously cached responses
+    # are discarded.
+    def memoize
+      return yield if memoizing?
+
+      begin
+        start_memoizing
+        yield if block_given?
+      ensure
+        stop_memoizing
+      end
+    end
+
+    # @private
+    def resource_cache
+      if memoizing?
+        Thread.current[:aws_memoization][:resource_cache] ||=
+          ResourceCache.new
+      end
+    end
+
+    # @private
+    def response_cache
+      if memoizing?
+        Thread.current[:aws_memoization][:response_cache] ||=
+          ResponseCache.new
+      end
+    end
+
+    # Causes all requests to return empty responses without making any
+    # requests against the live services.  This does not attempt to
+    # mock the services.
+    # @return [nil]
+    def stub!
+      config(:stub_requests => true)
+      nil
+    end
+
+  end
+end

data/lib/aws/configurable.rb

@@ -0,0 +1,36 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/configuration'
+
+module AWS
+
+  # @private
+  module Configurable
+
+    module ClassMethods
+
+      def make_configurable(name, opts = {})
+        Configuration.add_parameter_type(self, name, opts)
+      end
+
+    end
+
+    def self.included(m)
+      m.extend ClassMethods
+      super
+    end
+
+  end
+
+end

data/lib/aws/configuration.rb

@@ -0,0 +1,272 @@
+# Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+
+require 'aws/default_signer'
+require 'aws/http/httparty_handler'
+require 'set'
+
+module AWS
+
+  # A configuration object for AWS interfaces and clients.
+  #
+  # == Configuring Credential
+  #
+  # In order to do anything with AWS you will need to assign credentials.
+  # The simplest method is to assing your credentials into the default
+  # configuration:
+  #
+  #   AWS.config(:access_key_id => 'KEY', :secret_access_key => 'SECRET')
+  #
+  # You can also export them into your environment and they will be picked up
+  # automatically:
+  #
+  #   export AWS_ACCESS_KEY_ID='YOUR_KEY_ID_HERE'
+  #   export AWS_SECRET_ACCESS_KEY='YOUR_SECRET_KEY_HERE'
+  #
+  # For compatability with other AWS gems, the credentials can also be
+  # exported like:
+  #
+  #   export AMAZON_ACCESS_KEY_ID='YOUR_KEY_ID_HERE'
+  #   export AMAZON_SECRET_ACCESS_KEY='YOUR_SECRET_KEY_HERE'
+  #
+  # == Modifying a Configuration
+  #
+  # Configuration objects are read-only.  If you need a different set of
+  # configuration values, call {#with}, passing in the updates
+  # and a new configuration object will be returned.
+  #
+  #   config = Configuration.new(:max_retires => 3)
+  #   new_config = config.with(:max_retries => 2)
+  #
+  #   config.max_retries #=> 3
+  #   new_config.max_retries #=> 2
+  #
+  # == Global Configuration
+  #
+  # The global default configuration can be found at {AWS.config}
+  #
+  class Configuration
+
+    # Creates a new Configuration object.
+    # @param options (see AWS.config)
+    # @option options (see AWS.config)
+    def initialize options = {}
+
+      @create_options = options.delete(:__create_options__) || {}
+
+      @overridden = options.delete(:__overridden__) ||
+        Set.new(options.keys.map { |k| k.to_sym })
+
+      @options = {
+        :ec2_endpoint => 'ec2.amazonaws.com',
+        :http_handler => Http::HTTPartyHandler.new,
+        :max_retries => 3,
+        :s3_endpoint => 's3.amazonaws.com',
+        :s3_multipart_threshold => 16 * 1024 * 1024,
+        :s3_multipart_min_part_size => 5 * 1024 * 1024,
+        :s3_multipart_max_parts => 10000,
+        :simple_db_endpoint => 'sdb.amazonaws.com',
+        :simple_db_consistent_reads => false,
+        :simple_email_service_endpoint => 'email.us-east-1.amazonaws.com',
+        :sns_endpoint => 'sns.us-east-1.amazonaws.com',
+        :sqs_endpoint => 'sqs.us-east-1.amazonaws.com',
+        :stub_requests => false,
+        :use_ssl => true,
+        :user_agent_prefix => nil,
+      }
+
+      {
+        'AWS_ACCESS_KEY_ID'        => :access_key_id,
+        'AWS_SECRET_ACCESS_KEY'    => :secret_access_key,
+        'AMAZON_ACCESS_KEY_ID'     => :access_key_id,
+        'AMAZON_SECRET_ACCESS_KEY' => :secret_access_key,
+      }.each_pair do |env_key, opt_key|
+        if ENV[env_key]
+          @options[opt_key] = ENV[env_key]
+        end
+      end
+
+      options.each do |(k,v)|
+        @options[k.to_sym] = v
+      end
+
+    end
+
+    # @return [Boolean] Returns true if web service requets should be 
+    #   made with HTTPS.
+    def use_ssl?
+      @options[:use_ssl]
+    end
+    alias_method :use_ssl, :use_ssl?
+
+    # @return [String] Your AWS account access key id credential.
+    def access_key_id
+      @options[:access_key_id]
+    end
+
+    # @return [String] Your AWS secret access key credential.
+    def secret_access_key
+      @options[:secret_access_key]
+    end
+
+    # Used to create a new Configuration object with the given modifications.
+    # The current configuration object is not modified.
+    #
+    #   AWS.config(:max_retries => 2)
+    #
+    #   no_retries_config = AWS.config.with(:max_retries => 0)
+    #
+    #   AWS.config.max_retries        #=> 2
+    #   no_retries_config.max_retries #=> 0
+    #
+    # You can use these configuration objects returned by #with to create
+    # AWS objects:
+    #
+    #   AWS::S3.new(:config => no_retries_config)
+    #   AWS::SQS.new(:config => no_retries_config)
+    #
+    # @param options (see AWS.config)
+    # @option options (see AWS.config)
+    # @return [Configuration] Copies the current configuration and returns
+    #   a new one with modifications as provided in +:options+.
+    def with options = {}
+      overridden = @overridden + options.keys.map { |k| k.to_sym }
+      self.class.new(@options.merge(options).
+                     merge(:__create_options__ => @create_options,
+                           :__overridden__ => overridden))
+    end
+
+    # @return [Integer] Maximum number of times to retry server errors.
+    def max_retries
+      @options[:max_retries]
+    end
+
+    # @return [String] The service endpoint for Amazon S3.
+    def s3_endpoint
+      @options[:s3_endpoint]
+    end
+
+    # @return [String] The default service endpoint for Amazon EC2.
+    def ec2_endpoint
+      @options[:ec2_endpoint]
+    end
+
+    # @return [String] The service endpoint for Amazon SimpleDB.
+    def simple_db_endpoint
+      @options[:simple_db_endpoint]
+    end
+
+    # @return [String] The service endpoint for Amazon SimpleEmailService.
+    def simple_email_service_endpoint
+      @options[:simple_email_service_endpoint]
+    end
+
+    # @return [String] The service endpoint for Amazon SNS.
+    def sns_endpoint
+      @options[:sns_endpoint]
+    end
+
+    # @return [String] The service endpoint for Amazon SQS.
+    def sqs_endpoint
+      @options[:sqs_endpoint]
+    end
+
+    # @return [Boolean] Returns true if all reads to SimpleDB default to
+    #   consistent reads.
+    def simple_db_consistent_reads?
+      @options[:simple_db_consistent_reads]
+    end
+
+    # @return [String,nil] Returns the prefix that is appended to the 
+    #   user agent string that is sent with all requests to AWS.
+    def user_agent_prefix
+      @options[:user_agent_prefix]
+    end
+
+    # @return [Object] Returns the current http handler.
+    def http_handler
+      @options[:http_handler]
+    end
+
+    # @return [Object] Returns the current request signer.
+    def signer
+      return @options[:signer] if @options[:signer]
+      raise "Missing credentials" unless access_key_id and secret_access_key
+      @options[:signer] ||= DefaultSigner.new(access_key_id, secret_access_key)
+    end
+
+    # @return [Object,nil] Returns the current logger.
+    def logger
+      @options[:logger]
+    end
+
+    # @return [Boolean] Returns true if this configuration causes
+    #   all AWS requests to return stubbed (empty) responses without making a
+    #   request to the actual service.
+    def stub_requests?
+      @options[:stub_requests]
+    end
+
+    # @return [Integer] Returns the number of bytes where files larger 
+    #   are uploaded to S3 in multiple parts.
+    def s3_multipart_threshold
+      @options[:s3_multipart_threshold]
+    end
+
+    # @return [Integer] The absolute minimum size (in bytes) each S3 multipart
+    #   segment should be.
+    def s3_multipart_min_part_size
+      @options[:s3_multipart_min_part_size]
+    end
+
+    # @return [Integer] The maximum number of parts to split a file into
+    #   when uploading to S3.
+    def s3_multipart_max_parts
+      @options[:s3_multipart_max_parts]
+    end
+
+    # @private
+    def inspect
+      "<#{self.class}>"
+    end
+
+    class << self
+
+      # @private
+      def add_parameter_type(klass, name, options = {})
+        if options[:needs]
+          define_method(name) do
+            unless @overridden.include?(name)
+              create_options = { :config => self }
+              options[:needs].each do |need|
+                create_options[need] = send(need)
+              end
+            end
+
+            return @options[name] if @options[name] and
+              (@overridden.include?(name) or
+               @create_options[name] == create_options)
+
+            @create_options[name] = create_options
+            @options[name] = klass.new(create_options)
+          end
+        else
+          define_method(name) do
+            @options[name] ||= klass.new(:config => self)
+          end
+        end
+      end
+
+    end
+  end
+end