s33r 0.3.1 → 0.4

data/lib/s33r/core.rb

@@ -4,6 +4,7 @@ require 'net/http'
 require 'net/https'
 require 'openssl'
 require 'xml/libxml'
+require 'parsedate'
 
 # Module to handle S3 operations which don't require an internet connection,
 # i.e. data validation and request-building operations;
@@ -24,13 +25,14 @@ module S33r
   PORT = 443
   NON_SSL_PORT = 80
   METADATA_PREFIX = 'x-amz-meta-'
-  # Size of each chunk (in bytes) to be sent per request when putting files.
+  # Size of each chunk (in bytes) to be sent per request when putting files (1Mb).
   DEFAULT_CHUNK_SIZE = 1048576
   AWS_HEADER_PREFIX = 'x-amz-'
   AWS_AUTH_HEADER_VALUE = "AWS %s:%s"
   INTERESTING_HEADERS = ['content-md5', 'content-type', 'date']
   # Headers which must be included with every request to S3.
   REQUIRED_HEADERS = ['Content-Type', 'Date']
+  # Canned ACLs made available by S3.
   CANNED_ACLS = ['private', 'public-read', 'public-read-write', 'authenticated-read']
   # HTTP methods which S3 will respond to.
   METHOD_VERBS = ['GET', 'PUT', 'HEAD', 'POST', 'DELETE']
@@ -38,6 +40,35 @@ module S33r
   BUCKET_LIST_MAX_MAX_KEYS = 1000
   # Default number of seconds an authenticated URL will last for (15 minutes).
   DEFAULT_EXPIRY_SECS = 60 * 15
+  # The namespace used for response body XML documents.
+  RESPONSE_NAMESPACE_URI = "http://s3.amazonaws.com/doc/2006-03-01/"
+  
+  # Permissions which can be set within a <Grant>
+  # (see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingPermissions.html).
+  # 
+  # NB I've missed out the WRITE_ACP permission as this is functionally
+  # equivalent to FULL_CONTROL.
+  PERMISSIONS = { 
+    :read => 'READ',  # permission to read
+    :write => 'WRITE',  # permission to write
+    :read_acl => 'READ_ACP',  # permission to read ACL settings
+    :all => 'FULL_CONTROL'  # do anything
+  }
+  
+  # Used for generating ACL XML documents.
+  NAMESPACE = 'xsi'
+  NAMESPACE_URI = 'http://www.w3.org/2001/XMLSchema-instance'
+  GRANTEE_TYPES = {
+    :amazon_customer => 'AmazonCustomerByEmail', 
+    :canonical_user => 'CanonicalUser',
+    :group => 'Group'
+  }
+  S3_GROUP_TYPES = {
+    :all_users => 'global/AllUsers',
+    :authenticated_users => 'global/AuthenticatedUsers',
+    :log_delivery => 's3/LogDelivery'
+  }
+  GROUP_ACL_URI_BASE = 'http://acs.amazonaws.com/groups/'
 
   # Build canonical string for signing;
   # modified (slightly) from the Amazon sample code.
@@ -50,11 +81,11 @@ module S33r
       end
     end
 
-    # these fields get empty strings if they don't exist.
+    # These fields get empty strings if they don't exist.
     interesting_headers['content-type'] ||= ''
     interesting_headers['content-md5'] ||= ''
 
-    # if you're using expires for query string auth, then it trumps date
+    # If you're using expires for query string auth, then it trumps date.
     if not expires.nil?
       interesting_headers['date'] = expires
     end
@@ -68,17 +99,19 @@ module S33r
       end
     end
 
-    # ignore everything after the question mark...
+    # Ignore everything after the question mark...
     buf << path.gsub(/\?.*$/, '')
 
-    # ...unless there is an acl or torrent parameter
+    # ...unless there is an acl, logging or torrent parameter
     if path =~ /[&?]acl($|&|=)/
       buf << '?acl'
     elsif path =~ /[&?]torrent($|&|=)/
       buf << '?torrent'
+    elsif path =~ /[&?]logging($|&|=)/
+      buf << '?logging'
     end
 
-    return buf
+    buf
   end
 
   # Get the value for the AWS authentication header.
@@ -106,8 +139,8 @@ module S33r
   end
 
   # Build the headers required with every S3 request (Date and Content-Type); 
-  # options hash can contain extra header settings, as follows:
-  # :date and :content_type are required headers, and set to defaults if not supplied
+  # options hash can contain extra header settings;
+  # +:date+ and +:content_type+ are required headers, and set to defaults if not supplied
   def add_default_headers(headers, options={})
     # set the default headers required by AWS
     missing_headers = REQUIRED_HEADERS - headers.keys
@@ -125,6 +158,7 @@ module S33r
   end
 
   # Add metadata headers, correctly prefixing them first.
+  # 
   # Returns headers with the metadata headers appended.
   def metadata_headers(headers, metadata={})
     unless metadata.empty?
@@ -168,38 +202,43 @@ module S33r
     end
     str
   end
-
-  # Build URLs from fragments.
-  # Does similar job to File.join but puts forward slash between arguments
-  # (only if it's not already there).
-  def url_join(*args)
-    url_start = ''
-    url_end = args.join('/')
-    
-    # string index where the scheme of the URL (xxxx://) ends
-    scheme_ends_at = (url_end =~ /:\/\//)
-    unless scheme_ends_at.nil?
-      scheme_ends_at = scheme_ends_at + 1
-      url_start = url_end[0..scheme_ends_at]
-      url_end = url_end[(scheme_ends_at + 1)..-1]
-    end
-    
-    # replace any multiple forward slashes (except those in the scheme)
-    url_end = url_end.gsub(/\/{2,}/, '/')
-    
-    url_start + url_end
+  
+  # Return the location of the ACL for a resource.
+  def s3_acl_path(bucket_name, resource_key)
+    s3_path(bucket_name, resource_key) + "?acl"
+  end
+  
+  # Return the location of the logging definition for a resource.
+  def s3_logging_path(bucket_name, resource_key)
+    s3_path(bucket_name, resource_key) + "?logging"
   end
   
-  # The public URL for this key (which only works if public-read ACL is set).
-  def s3_public_url(bucket_name, resource_key)
-    "http://" + HOST + '/' + bucket_name + '/' + resource_key
+  # Prepend scheme and HOST to path.
+  def s3_url(path)
+    "http://" + HOST + path
+  end
+  
+  # Public readable URL for a bucket and resource.
+  def s3_public_url(bucket_name, resource_key='')
+    path = s3_path(bucket_name, resource_key)
+    s3_url(path)
+  end
+  
+  # Returns the path for this bucket and key.
+  def s3_path(bucket_name, resource_key)
+    path = '/' + bucket_name
+    path += '/' + resource_key unless '' == resource_key or resource_key.nil?
+    path
   end
   
   # Generate a get-able URL for an S3 resource key which passes authentication in querystring.
-  # int expires: when the URL expires (seconds since the epoch)
+  # 
+  # int +expires+: when the URL expires (seconds since the epoch); NB you can use S33r.parse_expiry 
+  # to generate a suitable value from a string.
   def s3_authenticated_url(aws_access_key, aws_secret_access_key, bucket_name, resource_key, 
-  expires)
-    path = '/' + bucket_name + '/' + resource_key
+  expires=nil)
+    path = s3_path(bucket_name, resource_key)
+    expires = S33r.parse_expiry(expires)
     
     canonical_string = generate_canonical_string('GET', path, {}, expires)
     signature = generate_signature(aws_secret_access_key, canonical_string)
@@ -207,10 +246,11 @@ module S33r
     querystring = generate_querystring({ 'Signature' => signature, 'Expires' => expires,
     'AWSAccessKeyId' => aws_access_key })
     
-    return s3_public_url(bucket_name, resource_key) + querystring
+    return s3_url(path) + querystring
   end
   
-  # Turn keys in a hash hsh into symbols.
+  # Turn keys in a hash +hsh+ into symbols.
+  # 
   # Returns a hash with 'symbolised' keys.
   def S33r.keys_to_symbols(hsh)
     symbolised = hsh.inject({}) do |symbolised, key_value|
@@ -218,4 +258,34 @@ module S33r
     end
     symbolised
   end
+  
+  # Parse an expiry date to seconds since the epoch.
+  # 
+  # +expires+ can be set to 'forever' to get a time 20 years in the future;
+  # 'default' to use the current time + DEFAULT_EXPIRY_SECS;
+  # or to a specific date (parseable by ParseDate); or to an integer
+  # representing seconds since the epoch.
+  # 
+  # TODO: testing for this
+  def S33r.parse_expiry(expires)
+    base_expires = Time.now.to_i
+    if 'forever' == expires
+      # 20 years (same as forever in computer terms)
+      expires = base_expires + (60 * 60 * 24 * 365.25 * 20).to_i
+    elsif 'default' == expires
+      # default to DEFAULT_EXPIRY_SECS seconds from now if expires not set
+      expires = base_expires + DEFAULT_EXPIRY_SECS
+    elsif expires.is_a?(String)
+      datetime_parts = ParseDate.parsedate(expires)
+      expires = Time.gm(*datetime_parts).to_i
+    end
+    expires
+  end
+  
+  # Remove the namespace declaration from S3 XML response bodies (libxml
+  # isn't fond of it).
+  def S33r.remove_namespace(xml_in)
+    namespace = RESPONSE_NAMESPACE_URI.gsub('/', '\/')
+    xml_in.gsub(/ xmlns="#{namespace}"/, '')
+  end
 end

data/lib/s33r/libxml_extensions.rb

@@ -1,7 +1,7 @@
 # Convenience methods for libxml classes.
 module XML
-  # Find first matching element and return its content
-  # (intended for use as a mixed-in method for Document instances).
+  # Find first element matching +xpath+ and return its content
+  # (intended for use as a mixed-in method for Document/Node instances).
   # 
   # +xpath+: XPath query to run against self.
   # 

data/lib/s33r/logging.rb

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'xml/libxml'
+require_gem 'builder'
+
+module S33r
+  # For manipulating logging directives on resources
+  # (see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/LoggingHowTo.html).
+  # 
+  # Calling LoggingResource.new (no arguments) will generate a blank instance
+  # which can be used to remove logging from a resource.
+  class LoggingResource
+    attr_reader :log_target, :log_prefix
+  
+    def initialize(log_target=nil, log_prefix=nil)
+      @log_target = log_target
+      @log_prefix = log_prefix
+    end
+    
+    # Generate a BucketLoggingStatus XML document for putting to the ?logging
+    # URL for a resource.
+    # 
+    #-- TODO: test generates correct XML
+    def to_xml
+      xml_str = ""
+      xml = Builder::XmlMarkup.new(:target => xml_str, :indent => 0)
+      
+      xml.instruct!
+      
+      # BucketLoggingStatus XML.
+      xml.BucketLoggingStatus({"xmlns" => RESPONSE_NAMESPACE_URI}) {
+        unless @log_target.nil? and @log_prefix.nil?
+          xml.LoggingEnabled {
+            xml.TargetBucket @log_target
+            xml.TargetPrefix @log_prefix
+          }
+        end
+      }
+      
+      xml_str
+    end
+    
+  end
+end

data/lib/s33r/named_bucket.rb

@@ -6,14 +6,14 @@ require File.join(File.dirname(__FILE__), 'client')
 module S33r
   # Wraps the S33r::Client class to make it more convenient for use with a single bucket.
   class NamedBucket < Client
-    attr_accessor :bucket_name, :strict, :public_contents, :dump_requests
+    attr_accessor :name, :strict, :public_contents, :dump_requests
     
     # Initialize an instance from a config_file. The config. file can include a separate
     # +options+ section specifying options specific to NamedBucket instances (see the initialize method
     # for more details).
     # Other options are as for S33r::Client.init.
     def NamedBucket.init(config_file)
-      aws_access_key, aws_secret_access_key, options, _ = super.class.load_config(config_file)
+      aws_access_key, aws_secret_access_key, options = super.class.load_config(config_file)
       NamedBucket.new(aws_access_key, aws_secret_access_key, options)
     end
   
@@ -27,21 +27,21 @@ module S33r
     def initialize(aws_access_key, aws_secret_access_key, options={}, &block)    
       super(aws_access_key, aws_secret_access_key, options)
       
-      @bucket_name = options[:default_bucket]
-      if @bucket_name.nil?
+      @name = options[:default_bucket]
+      if @name.nil?
         raise S33rException::MissingBucketName, "NamedBucket cannot be initialised without specifying\
         a :default_bucket option"
       end
 
       # holds a BucketListing instance
-      @bucket_listing = nil
+      @listing = nil
 
       # all content should be created as public-read
       @public_contents = (true == options[:public_contents])
       @client_headers.merge!(canned_acl_header('public-read')) if @public_contents
       
       @strict = (true == options[:strict])
-      if @strict && !bucket_exists?(@bucket_name)
+      if @strict && !bucket_exists?(@name)
         raise S33rException::MissingResource, "Non-existent bucket #{@bucket_name} specified"
       end
       
@@ -60,24 +60,23 @@ module S33r
     
     # Get a single object from a bucket as a blob.
     def [](key)
-      get_resource(@bucket_name, key).body
+      get_resource(@name, key).body
     end
 
     # Get a BucketListing instance for the content of this bucket.
     def listing
-      _, @bucket_listing = list_bucket(@bucket_name)
-      @bucket_listing
+      list_bucket(@name)
     end
     
     # Does this bucket exist?
     # Returns true if the bucket this NamedBucket is mapped to exists.
     def exists?
-      bucket_exists?(@bucket_name)
+      bucket_exists?(@name)
     end
     
     # Delete the bucket.
     def destroy(headers={}, options={})
-      delete_bucket(@bucket_name, headers, options)
+      delete_bucket(@name, headers, options)
     end
     
     # Get a pretty list of the keys in the bucket.
@@ -93,22 +92,22 @@ module S33r
     # Does the given key exist in the bucket?
     # Returns boolean
     def key_exists?(key)
-      head_resource(@bucket_name, key).ok?
+      resource_exists?(@name, key)
     end
 
     # Put a string into a key inside the bucket.
     def put_text(string, resource_key, headers={})
-      super(string, @bucket_name, resource_key, headers)
+      super(string, @name, resource_key, headers)
     end
 
     # Put a file into the bucket.
     def put_file(filename, resource_key=nil, headers={}, options={})
-      super(filename, @bucket_name, resource_key, headers, options)
+      super(filename, @name, resource_key, headers, options)
     end
     
     # Put a generic stream (e.g. from a file handle) into the bucket.
     def put_stream(data, resource_key, headers={})
-      put_resource(@bucket_name, resource_key, data, headers)
+      put_resource(@name, resource_key, data, headers)
     end
     
     # Delete an object from the bucket.
@@ -116,7 +115,7 @@ module S33r
     # and trying to delete a non-existent key (both return a 204).
     # If you want to test for existence first, use key_exists?.
     def delete_resource(resource_key, headers={})
-      super(@bucket_name, resource_key, headers)
+      super(@name, resource_key, headers)
       listing
     end
     
@@ -125,7 +124,7 @@ module S33r
     # 
     # +expires+: time in secs since the epoch when the link should become invalid.
     def s3_authenticated_url(resource_key, expires=(Time.now.to_i + DEFAULT_EXPIRY_SECS))
-      super(@aws_access_key, @aws_secret_access_key, @bucket_name, resource_key, expires)
+      super(@aws_access_key, @aws_secret_access_key, @name, resource_key, expires)
     end
   end
 end

data/lib/s33r/s33r_exception.rb

@@ -30,6 +30,17 @@ module S33r
     
     class S3FallenOver < Exception
     end
+    
+    class InvalidS3GroupType < Exception
+    end
+    
+    class InvalidPermission < Exception
+    end
+    
+    # Raised if a bucket cannot be used as a log target
+    # (i.e. if LogDelivery permissions not set - see S33r::S3ACL::ACLDoc.add_log_target_grants)
+    class BucketNotLogTargetable < Exception
+    end
 
   end
 end

data/lib/s33r/s33r_http.rb

@@ -9,8 +9,9 @@ class Net::HTTPResponse
   attr_writer :body
   
   def check_s3_availability
-    raise S33rException::S3FallenOver, "S3 has fallen over! (got a #{code} code in response)" \
     if (500..503).include? code.to_i
+      raise S33rException::S3FallenOver, "S3 has fallen over! (got a #{code} code in response)"
+    end
   end
 
   def ok?

data/lib/s33r/s3_acl.rb

@@ -0,0 +1,337 @@
+require 'rubygems'
+require 'xml/libxml'
+require_gem 'builder'
+require File.join(File.dirname(__FILE__), 's33r_exception')
+
+module S33r
+  # S3 ACL handling.
+  # 
+  # NB an individual ACL for an object can only contain <= 100 grants.
+  module S3ACL
+    
+    # An S3 ACL document, incorporating one or more Grants
+    # (see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingACL.html).
+    # 
+    # Represents both retrieved ACL XML or can be built up 
+    # using objects and converted to XML.
+    # NB the ACLDoc is oblivious to the resource it is going 
+    # to be applied to.
+    class ACLDoc
+      # List of grants to be applied.
+      attr_accessor :grants, :owner
+      
+      # +owner+: S33r::S3ACL::CanonicalUser instance
+      def initialize(owner, grants=[])
+        @grants = grants
+        @owner = owner
+      end
+      
+      # Create an ACLDoc instance from a raw Access Control Policy XML document.
+      # 
+      # +acl_xml+ is a raw Access Control Policy XML string (NOT libxml Document or Node).
+      # 
+      # Returns nil if the ACL XML is nil.
+      def self.from_xml(acl_xml)
+        return nil if acl_xml.nil?
+      
+        acl_xml = S33r.remove_namespace(acl_xml)
+        doc = XML.get_xml_doc(acl_xml)
+        
+        owner_xml = doc.find('//Owner').to_a.first
+        owner = CanonicalUser.from_xml(owner_xml)
+        
+        grants = []
+        doc.find('//AccessControlList/Grant').to_a.each do |g|
+          grantee_xml = g.find('Grantee').to_a.first
+          grantee = Grantee.from_xml(grantee_xml)
+          permission = g.xget('Permission')
+          
+          grants << Grant.new(grantee, permission)
+        end
+        
+        ACLDoc.new(owner, grants)
+      end
+      
+      # Generate AccessControlPolicy XML document.
+      def to_xml
+        xml_str = ""
+        xml = Builder::XmlMarkup.new(:target => xml_str, :indent => 0)
+        
+        xml.instruct!
+        
+        # Access control policy XML.
+        xml.AccessControlPolicy({"xmlns" => RESPONSE_NAMESPACE_URI}) {
+          xml.Owner {
+            xml.ID owner.user_id
+            xml.DisplayName owner.display_name
+          }
+          xml.AccessControlList {
+            grants.each do |grant|
+              xml << grant.to_xml
+            end
+          }
+        }
+        
+        xml_str
+      end
+      
+      # Add a grant to the ACL document.
+      # 
+      # Returns true if grant was added;
+      # false otherwise (grant already exists).
+      def add_grant(grant)
+        if @grants.include?(grant)
+          return false
+        else
+          @grants << grant
+          return true
+        end
+      end
+      
+      # Remove a grant from the ACL document. Note that if you
+      # set a grant for an AmazonCustomer, you want be able to remove it by
+      # specifying the same grant. This is because grants set by AmazonCustomer 
+      # are converted at the S3 end into CanonicalUser grants - so you will need 
+      # to remove a CanonicalUser grant instead. See Grant.for_amazon_customer 
+      # for a few more details.
+      # 
+      # Returns true if grant was removed;
+      # false if it wasn't in the document.
+      def remove_grant(grant)
+        @grants.delete_if { |g| grant == g }
+      end
+      
+      # Does the ACL contain a grant for public reads?
+      # (i.e. grants holds a Grant object for :all_users with :read permission)
+      def public_readable?
+        pr_grant = Grant.public_read_grant
+        grants.each do |g|
+          return true if pr_grant == g
+        end
+        return false
+      end
+      
+      # Add a public READ permission to this instance.
+      def add_public_read_grants
+        add_grant(Grant.public_read_grant)
+      end
+      
+      # Does the ACL make the associated resource available as a log target?
+      def log_targetable?
+        log_target_grants = Grant.log_target_grants
+        log_target_grants.each { |g| return false if !grants.include?(g) }
+        return true
+      end
+      
+      # Add permissions to an instances which give READ_ACL
+      # and WRITE permissions to the LogDelivery group. Used
+      # to enable a bucket as a logging destination.
+      # 
+      # Returns true if grants added, false otherwise
+      # (if already a log target).
+      def add_log_target_grants
+        if log_targetable?
+          return false
+        else
+          Grant.log_target_grants.each { |g| add_grant(g) }
+          return true
+        end
+      end
+      
+      # Remove log target ACLs from the document.
+      # 
+      # Returns true if all log target grants were removed;
+      # false otherwise.
+      # 
+      # NB even if this method returns false, that doesn't mean
+      # the bucket is still a log target. Use log_targetable? to check
+      # whether a bucket can be used as a log target.
+      def remove_log_target_grants
+        ok = true
+        Grant.log_target_grants.each { |g| ok = ok and remove_grant(g) }
+        ok
+      end
+      
+    end
+  
+    # Representation of an S3 Grant 
+    # (see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingGrantees.html).
+    # 
+    # A Grant consists of a Grantee and a permission they are to be 
+    # assigned.
+    class Grant
+      attr_accessor :grantee, :permission
+      
+      # permission: one of the keys in the PERMISSIONS hash or a raw permission string
+      def initialize(grantee, permission)
+        @grantee = grantee
+        if permission.is_a? String
+          @permission = permission
+        else
+          @permission = PERMISSIONS[permission]
+        end
+        raise InvalidPermission, "Permission #{permission.to_s} is not a valid permission specifier" if @permission.nil?
+      end
+      
+      # Note that setting a grant for an Amazon customer is the
+      # same as setting a grant for the CanonicalUser who owns the 
+      # specified email address. So when you get the ACL back, it will
+      # actually contain a CanonicalUser grant.
+      def Grant.for_amazon_customer(email_address,  permission)
+        Grant.new(AmazonCustomer.new(email_address), permission) 
+      end
+      
+      def Grant.for_canonical_user(id, display_name, permission)
+        Grant.new(CanonicalUser.new(id, display_name), permission)
+      end
+      
+      def Grant.for_group(group_type, permission)
+        Grant.new(Group.new(group_type), permission)
+      end
+      
+      # Generator for a Grant which gives READ permissions to the AllUsers
+      # group type.
+      def Grant.public_read_grant
+        Grant.new(Group.new(:all_users), :read)
+      end
+      
+      # Generator for a grant which gives the LogDelivery group
+      # write and read_acl permissions on a bucket.
+      # 
+      # Returns an array with the two required Grant instances.
+      def Grant.log_target_grants
+        log_delivery_group = Group.new(:log_delivery)
+        [Grant.new(log_delivery_group, :read_acl), Grant.new(log_delivery_group, :write)]
+      end
+      
+      # Convert a Grant object into an XML fragment.
+      def to_xml
+        xml_str = ""
+        xml = S33r::OrderlyXmlMarkup.new(:target => xml_str, :indent => 0)
+        
+        # <Grant> element.
+        xml.Grant {
+          xml.Grantee({"xmlns:#{NAMESPACE}" => NAMESPACE_URI, "xsi:type" => @grantee.grantee_type}) {
+            case @grantee.grantee_type
+              when GRANTEE_TYPES[:amazon_customer]
+                xml.EmailAddress @grantee.email_address
+              when GRANTEE_TYPES[:canonical_user]
+                xml.ID @grantee.user_id
+                xml.DisplayName @grantee.display_name
+              when GRANTEE_TYPES[:group]
+                xml.URI GROUP_ACL_URI_BASE + @grantee.group_type
+            end
+          }
+          xml.Permission @permission
+        }
+        
+        xml_str
+      end
+      
+      def ==(obj)
+        if !obj.is_a?(Grant)
+          return false
+        end
+        if obj.permission != self.permission or obj.grantee != self.grantee
+          return false
+        end
+        return true
+      end
+      
+    end
+
+    # Abstract representation of an S3 Grantee.
+    class Grantee
+      attr_reader :grantee_type
+      
+      def ==(obj)
+        if !obj.is_a?(Grantee)
+          return false
+        end
+        instance_variables.each do |var|
+          method_name = var.gsub(/^@/, '')
+          if self.send(method_name) != obj.send(method_name)
+            return false
+          end
+        end
+        return true
+      end
+      
+      def method_missing(*args)
+        nil
+      end
+      
+      def self.from_xml(grantee_xml)
+        grantee_type = grantee_xml['type']
+
+        case grantee_type
+          when GRANTEE_TYPES[:amazon_customer]
+            AmazonCustomer.new(grantee_xml.xget('EmailAddress'))
+          when GRANTEE_TYPES[:canonical_user]
+            CanonicalUser.from_xml(grantee_xml)
+          when GRANTEE_TYPES[:group]
+            uri = grantee_xml.xget('URI')
+            # last part of the path is the group type
+            path = uri.gsub(/#{GROUP_ACL_URI_BASE}/, '')
+
+            group_type = :all_users
+            S3_GROUP_TYPES.each { |k,v| group_type = k if v == path }
+            Group.new(group_type)
+        end
+      end
+      
+    end
+    
+    # An Amazon customer for the purposes of assigning permissions.
+    class AmazonCustomer < Grantee
+      attr_accessor :email_address
+      
+      def initialize(email_address)
+        @grantee_type = GRANTEE_TYPES[:amazon_customer]
+        @email_address = email_address
+      end
+    end
+    
+    # An S3 user.
+    class CanonicalUser < Grantee
+      attr_accessor :user_id, :display_name
+  
+      # +owner_xml_doc+: XML::Document or Node instance, representing an <Owner> node from 
+      # inside a ListBucketResult <Contents> element 
+      # (see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/)
+      # or an ACL <Grantee> element.
+      def initialize(user_id, display_name)
+        @grantee_type = GRANTEE_TYPES[:canonical_user]
+        @user_id = user_id
+        @display_name = display_name
+      end
+      
+      # Create a user object from an XML fragment with 
+      # ID and DisplayName elements. (Both ACL documents and 
+      # bucket listings represent users this way.)
+      def self.from_xml(user_xml_doc)
+        user_id = user_xml_doc.xget('ID')
+        display_name = user_xml_doc.xget('DisplayName')
+        new(user_id, display_name)
+      end
+    end
+    
+    # One of the predefined S3 groups.
+    # 
+    # A group must have a type (AllUsers or AuthenticatedUsers).
+    class Group < Grantee
+      attr_accessor :group_type
+      
+      # The type of group. A key from S3_GROUP_TYPES to 
+      # one of the pre-defined Amazon group types.
+      def initialize(group_type)
+        unless S3_GROUP_TYPES.has_key?(group_type)
+          raise InvalidS3GroupType, 'No such group type #{group_type}'
+        end
+        @group_type = S3_GROUP_TYPES[group_type]
+        @grantee_type = GRANTEE_TYPES[:group]
+      end
+    end
+    
+  end
+end