aws_sdk 3.1.5

data/lib/aws/s3.rb

@@ -0,0 +1,135 @@
+# Copyright 2011-2012 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/core'
+require 'aws/s3/config'
+
+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
+
+    AWS.register_autoloads(self) do
+      autoload :AccessControlList,            'access_control_list'
+      autoload :ACLObject,                    'acl_object'
+      autoload :Bucket,                       'bucket'
+      autoload :BucketCollection,             'bucket_collection'
+      autoload :BucketLifecycleConfiguration, 'bucket_lifecycle_configuration'
+      autoload :BucketVersionCollection,      'bucket_version_collection'
+      autoload :Client,                       'client'
+      autoload :DataOptions,                  'data_options'
+      autoload :Errors,                       'errors'
+      autoload :MultipartUpload,              'multipart_upload'
+      autoload :MultipartUploadCollection,    'multipart_upload_collection'
+      autoload :ObjectCollection,             'object_collection'
+      autoload :ObjectMetadata,               'object_metadata'
+      autoload :ObjectUploadCollection,       'object_upload_collection'
+      autoload :ObjectVersion,                'object_version'
+      autoload :ObjectVersionCollection,      'object_version_collection'
+      autoload :PaginatedCollection,          'paginated_collection'
+      autoload :Policy,                       'policy'
+      autoload :PrefixAndDelimiterCollection, 'prefix_and_delimiter_collection'
+      autoload :PrefixedCollection,           'prefixed_collection'
+      autoload :PresignedPost,                'presigned_post'
+      autoload :Request,                      'request'
+      autoload :S3Object,                     's3_object'
+      autoload :Tree,                         'tree'
+      autoload :UploadedPart,                 'uploaded_part'
+      autoload :UploadedPartCollection,       'uploaded_part_collection'
+    end
+
+    include Core::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,250 @@
+# Copyright 2011-2012 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
+  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

data/lib/aws/s3/acl_object.rb

@@ -0,0 +1,264 @@
+# Copyright 2011-2012 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 'rexml/text'
+
+module AWS
+  class S3
+
+    # Common methods for AccessControlList and related objects.
+    module ACLObject
+
+      # @private
+      def initialize(opts = {}); end
+
+      # @private
+      def body_xml; ""; end
+
+      # @private
+      def stag
+        element_name
+      end
+
+      # @private
+      def element_name
+        self.class.name[/::([^:]*)$/, 1]
+      end
+
+      # Returns the XML representation of the object.  Generally
+      # you'll want to call this on an AccessControlList object,
+      # which will yield an XML representation of the ACL that you
+      # can send to S3.
+      def to_s
+        if body_xml.empty?
+          "<#{stag}/>"
+        else
+          "<#{stag}>#{body_xml}</#{element_name}>"
+        end
+      end
+
+      # (see #to_s)
+      def to_xml
+        to_s
+      end
+
+      # Returns true if and only if this object is valid according
+      # to S3's published ACL schema.  In particular, this will
+      # check that all required attributes are provided and that
+      # they are of the correct type.
+      def valid?
+        validate!
+      rescue => e
+        false
+      else
+        true
+      end
+
+      # Raises an exception unless this object is valid according to
+      # S3's published ACL schema.
+      # @see #valid?
+      def validate!; end
+
+      # @private
+      def validate_input(name, value, context = nil)
+        send("validate_#{name}_input!", value, context)
+      end
+
+      # @private
+      module ClassMethods
+
+        def string_attr(element_name, options = {})
+          method_name = options[:method_name] ||
+            Core::Inflection.ruby_name(element_name)
+
+          attr_accessor(method_name)
+          setter_option(method_name)
+          string_input_validator(method_name)
+          validate_string(method_name) if options[:required]
+          body_xml_string_content(element_name, method_name)
+        end
+
+        def object_attr(klass, options = {})
+          base_name = klass.name[/::([^:]*)$/, 1]
+          method_name = Core::Inflection.ruby_name(base_name)
+          cast = options[:cast] || Hash
+
+          attr_reader(method_name)
+          setter_option(method_name)
+          object_setter(klass, method_name, cast)
+          object_input_validator(klass, base_name, method_name, cast)
+          validate_object(method_name) if options[:required]
+          body_xml_content(method_name)
+        end
+
+        def object_list_attr(list_element, klass, options = {})
+          base_name = klass.name[/::([^:]*)$/, 1]
+          method_name = Core::Inflection.ruby_name(options[:method_name].to_s || list_element)
+          default_value = nil
+          default_value = [] if options[:required]
+
+          attr_reader(method_name)
+          setter_option(method_name) { [] if options[:required] }
+          object_list_setter(klass, method_name)
+          object_list_input_validator(klass, base_name, method_name)
+          validate_list(method_name)
+          body_xml_list_content(list_element, method_name)
+        end
+
+        def setter_option(method_name)
+          Core::MetaUtils.class_extend_method(self, :initialize) do |*args|
+            opts = args.last || {}
+            instance_variable_set("@#{method_name}", yield) if block_given?
+            key = method_name.to_sym
+
+            if opts.has_key?(key)
+              value = opts[key]
+              validate_input(method_name, value, "for #{method_name} option")
+              self.send("#{method_name}=", value)
+            end
+            super(opts)
+          end
+        end
+
+        def string_input_validator(method_name)
+          input_validator(method_name) do |value, context|
+            raise ArgumentError.new("expected string"+context) unless
+              value.respond_to?(:to_str)
+          end
+        end
+
+        def object_input_validator(klass, base_name, method_name, cast)
+          input_validator(method_name) do |value, context|
+            if value.kind_of?(cast)
+              klass.new(value).validate!
+            else
+              raise ArgumentError.new("expected #{base_name} object or hash"+context) unless
+                value.nil? or value.kind_of? klass
+            end
+          end
+        end
+
+        def object_list_input_validator(klass, base_name, method_name)
+          input_validator(method_name) do |value, context|
+            raise ArgumentError.new("expected array"+context) unless value.kind_of?(Array)
+            value.each do |member|
+              if member.kind_of?(Hash)
+                klass.new(member).validate!
+              else
+                raise ArgumentError.new("expected array#{context} "+
+                                        "to contain #{base_name} objects "+
+                                        "or hashes") unless
+                  member.kind_of? klass
+              end
+            end
+          end
+        end
+
+        def input_validator(method_name, &blk)
+          validator = "__validator__#{blk.object_id}"
+          Core::MetaUtils.class_extend_method(self, validator, &blk)
+          Core::MetaUtils.class_extend_method(self, "validate_#{method_name}_input!") do |*args|
+            (value, context) = args
+            context = " "+context if context
+            context ||= ""
+            send(validator, value, context)
+          end
+        end
+
+        def object_setter(klass, method_name, cast)
+          define_method("#{method_name}=") do |value|
+            validate_input(method_name, value)
+            if value.kind_of?(cast)
+              value = klass.new(value)
+            end
+            instance_variable_set("@#{method_name}", value)
+          end
+        end
+
+        def object_list_setter(klass, method_name)
+          define_method("#{method_name}=") do |value|
+            validate_input(method_name, value)
+            list = value.map do |member|
+              if member.kind_of?(Hash)
+                klass.new(member)
+              else
+                member
+              end
+            end
+            instance_variable_set("@#{method_name}", list)
+          end
+        end
+
+        def validate_string(method_name)
+          Core::MetaUtils.class_extend_method(self, :validate!) do
+            super()
+            raise "missing #{method_name}" unless send(method_name)
+          end
+        end
+
+        def validate_object(method_name)
+          Core::MetaUtils.class_extend_method(self, :validate!) do
+            super()
+            raise "missing #{method_name}" unless send(method_name)
+            send(method_name).validate!
+          end
+        end
+
+        def validate_list(method_name)
+          Core::MetaUtils.class_extend_method(self, :validate!) do
+            super()
+            raise "missing #{method_name}" unless send(method_name)
+            send(method_name).each { |member| member.validate! }
+          end
+        end
+
+        def body_xml_string_content(element_name, method_name)
+          add_xml_child(method_name) do |value|
+            normalized = REXML::Text.normalize(value.to_s)
+            "<#{element_name}>#{normalized}</#{element_name}>"
+          end
+        end
+
+        def body_xml_content(method_name)
+          add_xml_child(method_name) { |value| value.to_s }
+        end
+
+        def body_xml_list_content(list_element, method_name)
+          add_xml_child(method_name) do |list|
+            list_content = list.map { |member| member.to_s }.join
+            if list_content.empty?
+              "<#{list_element}/>"
+            else
+              "<#{list_element}>#{list_content}</#{list_element}>"
+            end
+          end
+        end
+
+        def add_xml_child(method_name)
+          Core::MetaUtils.class_extend_method(self, :body_xml) do
+            xml = super()
+            value = send(method_name)
+            xml += yield(value) if value
+            xml
+          end
+        end
+
+      end
+
+      def self.included(m)
+        m.extend(ClassMethods)
+      end
+
+    end
+  end
+end