dbourguignon-aws-s3 0.6.3

data/lib/aws/s3/owner.rb

@@ -0,0 +1,44 @@
+module AWS
+  module S3
+    # Entities in S3 have an associated owner (the person who created them). The owner is a canonical representation of an 
+    # entity in the S3 system. It has an <tt>id</tt> and a <tt>display_name</tt>. 
+    # 
+    # These attributes can be used when specifying a ACL::Grantee for an ACL::Grant.
+    #
+    # You can retrieve the owner of the current account by calling Owner.current.
+    class Owner
+      undef_method :id if method_defined?(:id) # Get rid of Object#id
+      include SelectiveAttributeProxy
+      
+      class << self
+        # The owner of the current account.
+        def current
+          response = Service.get('/')
+          new(response.parsed['owner']) if response.parsed['owner']
+        end
+        memoized :current
+      end
+      
+      def initialize(attributes = {}) #:nodoc:
+        @attributes = attributes
+      end
+      
+      def ==(other_owner) #:nodoc:
+        hash == other_owner.hash
+      end
+      
+      def hash #:nodoc
+        [id, display_name].join.hash
+      end
+      
+      private
+        def proxiable_attribute?(name)
+          valid_attributes.include?(name)
+        end
+        
+        def valid_attributes
+          %w(id display_name)
+        end
+    end
+  end
+end

data/lib/aws/s3/parsing.rb

@@ -0,0 +1,99 @@
+#:stopdoc:
+module AWS
+  module S3
+    module Parsing
+      class << self
+        def parser=(parsing_library)
+          XmlParser.parsing_library = parsing_library
+        end
+        
+        def parser
+          XmlParser.parsing_library
+        end
+      end
+      
+      module Typecasting
+        def typecast(object)
+          case object
+          when Hash
+            typecast_hash(object)
+          when Array
+            object.map {|element| typecast(element)}
+          when String
+            CoercibleString.coerce(object)
+          else
+            object
+          end
+        end
+        
+        def typecast_hash(hash)
+          if content = hash['__content__']  
+            typecast(content)
+          else
+            keys   = hash.keys.map {|key| key.underscore}
+            values = hash.values.map {|value| typecast(value)}
+            keys.inject({}) do |new_hash, key|
+              new_hash[key] = values.slice!(0)
+              new_hash
+            end
+          end
+        end
+      end
+      
+      class XmlParser < Hash
+        include Typecasting
+        
+        class << self
+          attr_accessor :parsing_library
+        end
+        
+        attr_reader :body, :xml_in, :root
+        
+        def initialize(body)
+          @body = body
+          unless body.strip.empty?
+            parse
+            set_root
+            typecast_xml_in
+          end
+        end
+      
+        private
+      
+          def parse
+            @xml_in = self.class.parsing_library.xml_in(body, parsing_options)
+          end
+          
+          def parsing_options
+            {
+              # Includes the enclosing tag as the top level key
+              'keeproot'      => true, 
+              # Makes tag value available via the '__content__' key
+              'contentkey'    => '__content__', 
+              # Always parse tags into a hash, even when there are no attributes 
+              # (unless there is also no value, in which case it is nil)
+              'forcecontent'  => true, 
+              # If a tag is empty, makes its content nil
+              'suppressempty' => nil,
+              # Force nested elements to be put into an array, even if there is only one of them
+              'forcearray'    => ['Contents', 'Bucket', 'Grant']
+            }
+          end
+          
+          def set_root
+            @root = @xml_in.keys.first.underscore
+          end
+          
+          def typecast_xml_in
+            typecast_xml = {}
+            @xml_in.dup.each do |key, value| # Some typecasting is destructive so we dup
+              typecast_xml[key.underscore] = typecast(value)
+            end
+            # An empty body will try to update with a string so only update if the result is a hash
+            update(typecast_xml[root]) if typecast_xml[root].is_a?(Hash)
+          end
+      end
+    end
+  end
+end
+#:startdoc:

data/lib/aws/s3/response.rb

@@ -0,0 +1,180 @@
+#:stopdoc:
+module AWS
+  module S3
+    class Base
+      class Response < String  
+        attr_reader :response, :body, :parsed
+        def initialize(response)
+          @response = response
+          @body     = response.body.to_s
+          super(body)
+        end
+    
+        def headers
+          headers = {}
+          response.each do |header, value|
+            headers[header] = value
+          end
+          headers
+        end
+        memoized :headers
+    
+        def [](header)
+          headers[header]
+        end
+    
+        def each(&block)
+          headers.each(&block)
+        end
+    
+        def code
+          response.code.to_i
+        end
+    
+        {:success      => 200..299, :redirect     => 300..399,
+         :client_error => 400..499, :server_error => 500..599}.each do |result, code_range|
+          class_eval(<<-EVAL, __FILE__, __LINE__)
+            def #{result}? 
+              return false unless response
+              (#{code_range}).include? code
+            end
+          EVAL
+        end
+    
+        def error?
+          !success? && response['content-type'] == 'application/xml' && parsed.root == 'error'
+        end
+    
+        def error
+          Error.new(parsed, self)
+        end
+        memoized :error
+    
+        def parsed
+          # XmlSimple is picky about what kind of object it parses, so we pass in body rather than self
+          Parsing::XmlParser.new(body)
+        end
+        memoized :parsed
+    
+        def inspect
+          "#<%s:0x%s %s %s>" % [self.class, object_id, response.code, response.message]
+        end
+      end
+    end
+    
+    class Bucket  
+      class Response < Base::Response
+        def bucket
+          parsed
+        end
+      end
+    end
+  
+    class S3Object
+      class Response < Base::Response
+        def etag
+          headers['etag'][1...-1]
+        end
+      end
+    end
+
+    class Service
+      class Response < Base::Response
+        def empty?
+          parsed['buckets'].nil?
+        end
+  
+        def buckets
+          parsed['buckets']['bucket'] || []
+        end
+      end
+    end
+    
+    module ACL
+      class Policy
+        class Response < Base::Response
+          alias_method :policy, :parsed
+        end
+      end
+    end
+    
+    # Requests whose response code is between 300 and 599 and contain an <Error></Error> in their body
+    # are wrapped in an Error::Response. This Error::Response contains an Error object which raises an exception
+    # that corresponds to the error in the response body. The exception object contains the ErrorResponse, so
+    # in all cases where a request happens, you can rescue ResponseError and have access to the ErrorResponse and
+    # its Error object which contains information about the ResponseError.
+    #
+    #   begin
+    #     Bucket.create(..)
+    #   rescue ResponseError => exception
+    #    exception.response
+    #    # => <Error::Response>
+    #    exception.response.error
+    #    # => <Error>
+    #   end
+    class Error
+      class Response < Base::Response
+        def error? 
+          true
+        end
+      
+        def inspect
+          "#<%s:0x%s %s %s: '%s'>" % [self.class.name, object_id, response.code, error.code, error.message]
+        end
+      end
+    end
+
+    # Guess response class name from current class name. If the guessed response class doesn't exist
+    # do the same thing to the current class's parent class, up the inheritance heirarchy until either
+    # a response class is found or until we get to the top of the heirarchy in which case we just use 
+    # the the Base response class.
+    #
+    # Important: This implemantation assumes that the Base class has a corresponding Base::Response.
+    class FindResponseClass #:nodoc:
+      class << self
+        def for(start)
+          new(start).find
+        end
+      end
+  
+      def initialize(start)
+        @container     = AWS::S3
+        @current_class = start
+      end
+  
+      def find
+        self.current_class = current_class.superclass until response_class_found?            
+        target.const_get(class_to_find)
+      end
+  
+      private
+        attr_reader :container
+        attr_accessor :current_class
+        
+        def target
+          container.const_get(current_name)
+        end
+        
+        def target?
+          container.const_defined?(current_name)
+        end
+        
+        def response_class_found?
+          target? && target.const_defined?(class_to_find)
+        end
+        
+        def class_to_find
+          :Response
+        end
+        
+        def current_name
+          truncate(current_class)
+        end
+        
+        def truncate(klass)
+          klass.name[/[^:]+$/]
+        end
+      end
+  end
+end
+#:startdoc:

data/lib/aws/s3/service.rb

@@ -0,0 +1,51 @@
+module AWS
+  module S3
+    # The service lets you find out general information about your account, like what buckets you have. 
+    # 
+    #   Service.buckets
+    #   # => []
+    class Service < Base
+      @@response = nil #:nodoc:
+      
+      class << self
+        # List all your buckets.
+        #
+        #   Service.buckets
+        #   # => []
+        #
+        # For performance reasons, the bucket list will be cached. If you want avoid all caching, pass the <tt>:reload</tt> 
+        # as an argument:
+        #
+        #   Service.buckets(:reload)
+        def buckets
+          response = get('/')
+          if response.empty?
+            []
+          else
+            response.buckets.map {|attributes| Bucket.new(attributes)}
+          end
+        end
+        memoized :buckets
+        
+        # Sometimes methods that make requests to the S3 servers return some object, like a Bucket or an S3Object. 
+        # Othertimes they return just <tt>true</tt>. Other times they raise an exception that you may want to rescue. Despite all these 
+        # possible outcomes, every method that makes a request stores its response object for you in Service.response. You can always 
+        # get to the last request's response via Service.response.
+        # 
+        #   objects = Bucket.objects('jukebox')
+        #   Service.response.success?
+        #   # => true
+        #
+        # This is also useful when an error exception is raised in the console which you weren't expecting. You can 
+        # root around in the response to get more details of what might have gone wrong.
+        def response
+          @@response
+        end
+        
+        def response=(response) #:nodoc:
+          @@response = response
+        end
+      end
+    end
+  end
+end

data/lib/aws/s3/version.rb

@@ -0,0 +1,12 @@
+module AWS
+  module S3
+    module VERSION #:nodoc:
+      MAJOR    = '0'
+      MINOR    = '6'
+      TINY     = '2' 
+      BETA     = Time.now.to_i.to_s
+    end
+    
+    Version = [VERSION::MAJOR, VERSION::MINOR, VERSION::TINY, VERSION::BETA].compact * '.'
+  end
+end

data/test/acl_test.rb

@@ -0,0 +1,254 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class PolicyReadingTest < Test::Unit::TestCase
+  
+  def setup
+    @policy = prepare_policy
+  end
+  
+  def test_policy_owner
+    assert_kind_of Owner, @policy.owner
+    assert_equal 'bb2041a25975c3d4ce9775fe9e93e5b77a6a9fad97dc7e00686191f3790b13f1', @policy.owner.id
+    assert_equal 'mmolina@onramp.net', @policy.owner.display_name
+  end
+  
+  def test_grants
+    assert @policy.grants
+    assert !@policy.grants.empty?
+    grant = @policy.grants.first
+    assert_kind_of ACL::Grant, grant
+    assert_equal 'FULL_CONTROL', grant.permission
+  end
+  
+  def test_grants_have_grantee
+    grant = @policy.grants.first
+    assert grantee = grant.grantee
+    assert_kind_of ACL::Grantee, grantee
+    assert_equal 'bb2041a25975c3d4ce9775fe9e93e5b77a6a9fad97dc7e00686191f3790b13f1', grantee.id
+    assert_equal 'mmolina@onramp.net', grantee.display_name
+    assert_equal 'CanonicalUser', grantee.type
+  end
+  
+  def test_grantee_always_responds_to_email_address
+    assert_nothing_raised do
+      @policy.grants.first.grantee.email_address
+    end
+  end
+  
+  private
+    def prepare_policy
+      ACL::Policy.new(parsed_policy)
+    end
+  
+    def parsed_policy
+      Parsing::XmlParser.new Fixtures::Policies.policy_with_one_grant
+    end
+end
+
+class PolicyWritingTest < PolicyReadingTest
+  
+  def setup
+    policy = prepare_policy
+    # Dump the policy to xml and retranslate it back from the xml then run all the tests in the xml reading
+    # test. This round tripping indirectly asserts that the original xml document is the same as the to_xml
+    # dump.
+    @policy = ACL::Policy.new(Parsing::XmlParser.new(policy.to_xml))
+  end
+  
+end
+
+class PolicyTest < Test::Unit::TestCase
+  def test_building_policy_by_hand
+    policy = grant = grantee = nil
+    assert_nothing_raised do
+      policy                = ACL::Policy.new
+      grant                 = ACL::Grant.new
+      grantee               = ACL::Grantee.new
+      grantee.email_address = 'marcel@vernix.org'
+      grant.permission      = 'READ_ACP'
+      grant.grantee         = grantee
+      policy.grants << grant
+      policy.owner          = Owner.new('id' => '123456789', 'display_name' => 'noradio')
+    end
+    
+    assert_nothing_raised do
+      policy.to_xml
+    end
+    
+    assert !policy.grants.empty?
+    assert_equal 1, policy.grants.size
+    assert_equal 'READ_ACP', policy.grants.first.permission
+  end
+  
+  def test_include?
+    policy = ACL::Policy.new(Parsing::XmlParser.new(Fixtures::Policies.policy_with_one_grant))
+    assert !policy.grants.include?(:public_read)
+    policy.grants << ACL::Grant.grant(:public_read)
+    assert policy.grants.include?(:public_read)
+    
+    assert policy.grants.include?(ACL::Grant.grant(:public_read))
+    [false, 1, '1'].each do |non_grant|
+      assert !policy.grants.include?(non_grant)
+    end
+  end
+  
+  def test_delete
+    policy = ACL::Policy.new(Parsing::XmlParser.new(Fixtures::Policies.policy_with_one_grant))
+    policy.grants << ACL::Grant.grant(:public_read)
+    assert policy.grants.include?(:public_read)
+    assert policy.grants.delete(:public_read)
+    assert !policy.grants.include?(:public_read)
+    [false, 1, '1'].each do |non_grant|
+      assert_nil policy.grants.delete(non_grant)
+    end
+  end
+  
+  def test_grant_list_comparison
+    policy  = ACL::Policy.new
+    policy2 = ACL::Policy.new
+    
+    grant_names = [:public_read, :public_read_acp, :authenticated_write]
+    grant_names.each {|grant_name| policy.grants << ACL::Grant.grant(grant_name)}
+    grant_names.reverse_each {|grant_name| policy2.grants << ACL::Grant.grant(grant_name)}
+    
+    assert_equal policy.grants, policy2.grants
+  end
+end
+
+class GrantTest < Test::Unit::TestCase
+  def test_permission_must_be_valid
+    grant = ACL::Grant.new
+    assert_nothing_raised do
+      grant.permission = 'READ_ACP'
+    end
+    
+    assert_raises(InvalidAccessControlLevel) do
+      grant.permission = 'not a valid permission'
+    end
+  end
+  
+  def test_stock_grants
+    assert_raises(ArgumentError) do
+      ACL::Grant.grant :this_is_not_a_stock_grant
+    end
+    
+    grant = nil
+    assert_nothing_raised do
+      grant = ACL::Grant.grant(:public_read)
+    end
+    
+    assert grant
+    assert_kind_of ACL::Grant, grant
+    assert_equal 'READ', grant.permission
+    assert grant.grantee
+    assert_kind_of ACL::Grantee, grant.grantee
+    assert_equal 'AllUsers', grant.grantee.group
+  end
+end
+
+class GranteeTest < Test::Unit::TestCase
+  def test_type_inference
+    grantee = ACL::Grantee.new
+    
+    assert_nothing_raised do
+      grantee.type
+    end
+    
+    assert_nil grantee.type
+    grantee.group = 'AllUsers'
+    assert_equal 'AllUsers', grantee.group
+    assert_equal 'Group', grantee.type
+    grantee.email_address = 'marcel@vernix.org'
+    assert_equal 'AmazonCustomerByEmail', grantee.type
+    grantee.display_name = 'noradio'
+    assert_equal 'AmazonCustomerByEmail', grantee.type
+    grantee.id = '123456789'
+    assert_equal 'CanonicalUser', grantee.type
+  end
+  
+  def test_type_is_extracted_if_present
+    grantee = ACL::Grantee.new('xsi:type' => 'CanonicalUser')
+    assert_equal 'CanonicalUser', grantee.type
+  end
+  
+  def test_type_representation
+    grantee = ACL::Grantee.new('uri' => 'http://acs.amazonaws.com/groups/global/AllUsers')
+    
+    assert_equal 'AllUsers Group', grantee.type_representation
+    grantee.group = 'AuthenticatedUsers'
+    assert_equal 'AuthenticatedUsers Group', grantee.type_representation
+    grantee.email_address = 'marcel@vernix.org'
+    assert_equal 'marcel@vernix.org', grantee.type_representation
+    grantee.display_name = 'noradio'
+    grantee.id = '123456789'
+    assert_equal 'noradio', grantee.type_representation
+  end
+end
+
+class ACLOptionProcessorTest < Test::Unit::TestCase
+  def test_empty_options
+    options = {}
+    assert_nothing_raised do
+      process! options
+    end
+    assert_equal({}, options)
+  end
+  
+  def test_invalid_access_level
+    options = {:access => :foo}
+    assert_raises(InvalidAccessControlLevel) do
+      process! options
+    end
+  end
+  
+  def test_valid_access_level_is_normalized
+    valid_access_levels = [
+      {:access     => :private},
+      {'access'    => 'private'},
+      {:access     => 'private'},
+      {'access'    => :private},
+      {'x-amz-acl' => 'private'},
+      {:x_amz_acl  => :private},
+      {:x_amz_acl  => 'private'},
+      {'x_amz_acl' => :private}
+    ]
+    
+    valid_access_levels.each do |options|
+      assert_nothing_raised do
+        process! options
+      end
+      assert_equal 'private', acl(options)
+    end
+    
+    valid_hyphenated_access_levels = [
+      {:access     => :public_read},
+      {'access'    => 'public_read'},
+      {'access'    => 'public-read'},
+      {:access     => 'public_read'},
+      {:access     => 'public-read'},
+      {'access'    => :public_read},
+      
+      {'x-amz-acl' => 'public_read'},
+      {:x_amz_acl  => :public_read},
+      {:x_amz_acl  => 'public_read'},
+      {:x_amz_acl  => 'public-read'},
+      {'x_amz_acl' => :public_read}
+    ]
+    
+    valid_hyphenated_access_levels.each do |options|
+      assert_nothing_raised do
+        process! options
+      end
+      assert_equal 'public-read', acl(options)
+    end
+  end
+  
+  private
+    def process!(options)
+      ACL::OptionProcessor.process!(options)
+    end
+    
+    def acl(options)
+      options['x-amz-acl']
+    end
+end