aws-sdk 1.0.0

data/lib/aws/resource_cache.rb

@@ -0,0 +1,39 @@
+# 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.
+
+module AWS
+
+  # @private
+  class ResourceCache
+
+    def initialize
+      @cache = {}
+    end
+
+    def store(key, attributes)
+      (@cache[key] ||= {}).merge!(attributes)
+    end
+
+    def cached?(key, attribute)
+      attributes = @cache[key] and
+        attributes.key?(attribute)
+    end
+
+    def get(key, attribute)
+      raise "No cached value for attribute :#{attribute} of #{key}" unless
+        cached?(key, attribute)
+      @cache[key][attribute]
+    end
+
+  end
+end

data/lib/aws/response.rb

@@ -0,0 +1,113 @@
+# 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/async_handle'
+
+module AWS
+
+  # @private
+  class Response
+
+    include AsyncHandle
+
+    # @return [AWS::Error] Returns nil unless the request failed.
+    #   Normally this will be nil unless you are using the Asynchronous 
+    #   interface.
+    attr_accessor :error
+    
+    # @return [Hash] The hash of options passed to the low level request 
+    #   method that generated this response.
+    attr_accessor :request_options
+
+    # @return [Symbol] The low-level request method that generated
+    #   this response
+    attr_accessor :request_type
+    
+    # @return [Http::Request] the HTTP request object 
+    attr_accessor :http_request
+
+    # @return [Http::Response] the HTTP response object 
+    attr_accessor :http_response
+
+    # @return [Boolean] true if the response is cached
+    attr_accessor :cached
+
+    # @param [Http::Request] http_request
+    # @param [Http::Response] http_request
+    def initialize http_request = nil, http_response = nil
+      @http_request = http_request
+      @http_response = http_response
+    end
+
+    # @return [Boolean] Teturns true unless there is a response error.
+    def successful?
+      error.nil?
+    end
+
+    # @return [Boolean] Returns true if the http request was throttled
+    #   by AWS.
+    def throttled?
+      !successful? and
+        parsed_body = XmlGrammar.parse(http_response.body) and
+        parsed_body.respond_to?(:code) and
+        parsed_body.code == "Throttling"
+    end
+
+    # @return [Boolean] Returns true if the http request timed out.
+    def timeout?
+      http_response.timeout?
+    end
+
+    # @private
+    def inspect
+      "<#{self.class}>"
+    end
+
+    def cache_key
+      [http_request.access_key_id,
+       http_request.host,
+       request_type,
+       serialized_options].join(":")
+    end
+
+    def serialized_options
+      serialize_options_hash(request_options)
+    end
+
+    private
+    def serialize_options_hash(hash)
+      "(" + hash.keys.sort_by(&:to_s).map do |key|
+        "#{key}=#{serialize_options_value(hash[key])}"
+      end.join(" ") + ")"
+    end
+
+    private
+    def serialize_options_value(value)
+      case value
+      when Hash
+        serialize_options_hash(value)
+      when Array
+        serialize_options_array(value)
+      else
+        value.inspect
+      end
+    end
+
+    private
+    def serialize_options_array(ary)
+      "[" + ary.map { |v| serialize_options_value(v) }.join(" ") +
+        "]"
+    end
+
+  end
+end

data/lib/aws/response_cache.rb

@@ -0,0 +1,50 @@
+# 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/resource_cache'
+
+module AWS
+
+  # @private
+  class ResponseCache
+
+    attr_reader :cached_responses
+
+    attr_reader :resource_cache
+
+    def initialize
+      @cached_responses = []
+      @indexed_responses = {}
+      @resource_cache = ResourceCache.new
+    end
+
+    def add(resp)
+      cached_responses.unshift(resp)
+      @indexed_responses[resp.cache_key] = resp if
+        resp.respond_to?(:cache_key)
+      @resource_cache = ResourceCache.new
+    end
+
+    def select(*types, &block)
+      cached_responses.select do |resp|
+        types.map { |t| t.to_s }.include?(resp.request_type.to_s) and
+          (block.nil? || block.call(resp))
+      end
+    end
+
+    def cached(resp)
+      @indexed_responses[resp.cache_key]
+    end
+
+  end
+end

data/lib/aws/s3.rb

@@ -0,0 +1,109 @@
+# 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/common'
+require 'aws/service_interface'
+require 'aws/s3/client'
+require 'aws/s3/errors'
+require 'aws/s3/bucket_collection'
+
+module AWS
+
+  # Provides an expressive, object-oriented interface to Amazon S3.
+  #
+  # To use Amazon S3 you must first 
+  # {sign up here}[http://aws.amazon.com/s3/].
+  #
+  # For more information about Amazon S3, see:
+  #
+  # * {Amazon S3}[http://aws.amazon.com/s3/]
+  # * {Amazon S3 Documentation}[http://aws.amazon.com/documentation/s3/]
+  #
+  # == Credentials
+  #
+  # You can setup default credentials for all AWS services via 
+  # AWS.config:
+  #
+  #   AWS.config(
+  #     :access_key_id => 'YOUR_ACCESS_KEY_ID',
+  #     :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')
+  # 
+  # Or you can set them directly on the S3 interface:
+  #
+  #   s3 = AWS::S3.new(
+  #     :access_key_id => 'YOUR_ACCESS_KEY_ID',
+  #     :secret_access_key => 'YOUR_SECRET_ACCESS_KEY')
+  #
+  # == Buckets Keys and Objects
+  #
+  # S3 stores objects in buckets.
+  #
+  # To create a bucket:
+  #
+  #   bucket = s3.buckets.create('mybucket')
+  #
+  # To get a bucket:
+  #
+  #   bucket = s3.buckets[:mybucket]
+  #   bucket = s3.buckets['mybucket']
+  #
+  # Listing buckets:
+  # 
+  #   s3.buckets.each do |bucket|
+  #     puts bucket.name
+  #   end
+  #
+  # See {Bucket} and {BucketCollection} for more information on working
+  # with S3 buckets.
+  #
+  # == Listing Objects
+  #
+  # Enumerating objects in a bucket:
+  #
+  #   bucket.objects.each do |object|
+  #     puts object.key #=> no data is fetched from s3, just a list of keys
+  #   end
+  #
+  # You can limit the list of objects with a prefix, or explore the objects
+  # in a bucket as a tree.  See {ObjectCollection} for more information.
+  #
+  # == Reading and Writing to S3
+  #
+  # Each object in a bucket has a unique key.
+  #
+  #   photo = s3.buckets['mybucket'].objects['photo.jpg']
+  #
+  # Writing to an S3Object:
+  #
+  #   photo.write(File.read('/some/photo.jpg'))
+  #
+  # Reading from an S3Object:
+  #
+  #   File.open("/some/path/on/disk.jpg", "w") do |f|
+  #     f.write(photo.read)
+  #   end
+  #
+  # See {S3Object} for more information on reading and writing to S3.
+  #
+  class S3
+
+    include ServiceInterface
+
+    # @return [BucketCollection] Returns a collection that represents all 
+    #  buckets in the account.
+    def buckets
+      BucketCollection.new(:config => @config)
+    end
+
+  end
+end

data/lib/aws/s3/access_control_list.rb

@@ -0,0 +1,252 @@
+# 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/s3/acl_object'
+
+module AWS
+  class S3
+
+    # Represents an access control list for S3 objects and buckets.  For example:
+    #
+    #   acl = AccessControlList.new
+    #   acl.grant(:full_control).
+    #     to(:canonical_user_id => "8a6925ce4adf588a4f21c32aa379004fef")
+    #   acl.to_xml                   # => '<AccessControlPolicy>...'
+    #
+    # You can also construct an AccessControlList from a hash:
+    #
+    #   AccessControlList.new(
+    #     :owner => { :id => "8a6925ce4adf588a4f21c32aa379004fef" },
+    #     :grants => [{ :grantee => {
+    #                     :canonical_user_id => "8a6925ce4adf588a4f21c32aa379004fef",
+    #                   },
+    #                   :permission => :full_control }]
+    #   )
+    #
+    # @see ACLObject
+    #
+    # @attr [AccessControlList::Owner] owner The owner of the access
+    #   control list.  You can set this as a hash, for example:
+    #    acl.owner = { :id => '8a6925ce4adf588a4f21c32aa379004fef' }
+    #   This attribute is required when setting an ACL.
+    #
+    # @attr [list of AccessControlList::Grant] grants The list of
+    #   grants.  You can set this as a list of hashes, for example:
+    #    acl.grants = [{ :grantee => { :canonical_user_id =>
+    #                                  "8a6925ce4adf588a4f21c32aa379004fef" },
+    #                    :permission => :full_control }]
+    class AccessControlList
+
+      # Represents an ACL owner.  In the default ACL, this is the
+      # bucket owner.
+      #
+      # @attr [String] id The canonical user ID of the ACL owner.
+      #   This attribute is required when setting an ACL.
+      #
+      # @attr [String] display_name The display name of the ACL
+      #   owner.  This value is ignored when setting an ACL.
+      class Owner
+        include ACLObject
+
+        string_attr "ID", :required => true
+        string_attr "DisplayName"
+      end
+
+      # Represents a user who is granted some kind of permission
+      # through a Grant.  There are three ways to specify a grantee:
+      #
+      # * You can specify the canonical user ID, for example.  When
+      #   you read an ACL from S3, all grantees will be identified
+      #   this way, and the display_name attribute will also be provided.
+      #
+      #    Grantee.new(:canonical_user_id => "8a6925ce4adf588a4f21c32aa379004fef")
+      #
+      # * You can specify the e-mail address of an AWS customer, for example:
+      #    Grantee.new(:amazon_customer_email => 'foo@example.com')
+      #
+      # * You can specify a group URI, for example:
+      #    Grantee.new(:group_uri => 'http://acs.amazonaws.com/groups/global/AllUsers')
+      #   For more details about group URIs, see:
+      #   http://docs.amazonwebservices.com/AmazonS3/latest/dev/ACLOverview.html
+      #
+      # When constructing a grantee, you must provide a value for
+      # exactly one of the following attributes:
+      #
+      # * +amazon_customer_email+
+      # * +canonical_user_id+
+      # * +group_uri+
+      #
+      # @attr [String] amazon_customer_email The e-mail address of
+      #   an AWS customer.
+      #
+      # @attr [String] canonical_user_id The canonical user ID of an
+      #   AWS customer.
+      #
+      # @attr [String] group_uri A URI that identifies a particular
+      #   group of users.
+      #
+      # @attr [String] display_name The display name associated with
+      #   the grantee.  This is provided by S3 when reading an ACL.
+      class Grantee
+        include ACLObject
+
+        SIGNAL_ATTRIBUTES = [:amazon_customer_email,
+                             :canonical_user_id,
+                             :group_uri]
+
+        string_attr "EmailAddress", :method_name => "amazon_customer_email"
+        string_attr "ID", :method_name => "canonical_user_id"
+        string_attr "URI", :method_name => "group_uri"
+        string_attr "DisplayName"
+
+        # (see ACLObject#validate!)
+        def validate!
+          attr = signal_attribute
+          raise "missing amazon_customer_email, canonical_user_id, "+
+            "or group_uri" unless attr
+          raise "display_name is invalid with #{attr}" if
+            attr != :canonical_user_id and display_name
+        end
+
+        # @private
+        def stag
+          if attr = signal_attribute
+            super + " xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"" +
+              " xsi:type=\"#{type_for_attr(attr)}\""
+          else
+            super
+          end
+        end
+
+        # @private
+        def signal_attribute
+          SIGNAL_ATTRIBUTES.find { |att| send(att) }
+        end
+
+        # @private
+        def type_for_attr(attr)
+          { :amazon_customer_email => "AmazonCustomerByEmail",
+            :canonical_user_id => "CanonicalUser",
+            :group_uri => "Group" }[attr]
+        end
+
+      end
+
+      # Represents the permission being granted in a Grant object.
+      # Typically you will not need to construct an instance of this
+      # class directly.
+      # @see Grant#permission
+      class Permission
+        include ACLObject
+
+        # The permission expressed as a symbol following Ruby
+        # conventions.  For example, S3's FULL_CONTROL permission
+        # will be returned as +:full_control+.
+        attr_reader :name
+
+        # @private
+        def initialize(name)
+          raise "expected string or symbol" unless
+            name.respond_to?(:to_str) or name.respond_to?(:to_sym)
+          @name = name.to_sym
+        end
+
+        def body_xml
+          name.to_s.upcase
+        end
+
+      end
+
+      # Represents a single grant in an ACL.  Both +grantee+ and
+      # +permission+ are required for each grant when setting an
+      # ACL.
+      #
+      # See
+      # http://docs.amazonwebservices.com/AmazonS3/latest/dev/ACLOverview.html
+      # for more information on how grantees and permissions are
+      # interpreted by S3.
+      #
+      # @attr [Grantee] grantee The user or users who are granted
+      #   access according to this grant.  You can specify this as a
+      #   hash:
+      #     grant.grantee = { :amazon_customer_email => "foo@example.com" }
+      #
+      # @attr [Permission or Symbol] permission The type of
+      #   permission that is granted by this grant.  Valid values are:
+      #   * +:read+
+      #   * +:write+
+      #   * +:read_acp+
+      #   * +:write_acp+
+      #   * +:full_control+
+      class Grant
+
+        include ACLObject
+
+        object_attr Grantee, :required => true
+        object_attr Permission, :required => true, :cast => Symbol
+
+      end
+
+      include ACLObject
+
+      # @private
+      def stag
+        super()+" xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\""
+      end
+
+      # @private
+      def element_name
+        "AccessControlPolicy"
+      end
+
+      class GrantBuilder
+
+        # @private
+        def initialize(acl, grant)
+          @acl = acl
+          @grant = grant
+        end
+
+        # Specifies the grantee.
+        #
+        # @param [Grantee or Hash] grantee A Grantee object or hash;
+        #   for example:
+        #    acl.grant(:full_control).to(:amazon_customer_email => "foo@example.com")
+        def to(grantee)
+          @grant.grantee = grantee
+          @acl.grants << @grant
+        end
+
+      end
+
+      # Convenience method for constructing a new grant and adding
+      # it to the ACL.  Example usage:
+      #
+      #   acl.grants.size               # => 0
+      #   acl.grant(:full_control).
+      #     to(:canonical_user_id => "8a6925ce4adf588a4f21c32aa379004fef")
+      #   acl.grants.size               # => 1
+      #
+      # @return [GrantBuilder]
+      def grant(permission)
+        GrantBuilder.new(self, Grant.new(:permission => permission))
+      end
+
+      object_attr Owner, :required => true
+      object_list_attr("AccessControlList", Grant,
+                       :required => true, :method_name => :grants)
+
+    end
+
+  end
+end