aws-s3 0.1.0

data/Rakefile

@@ -0,0 +1,284 @@
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+
+require File.dirname(__FILE__) + '/lib/aws/s3'
+
+def library_root
+  File.dirname(__FILE__)
+end
+
+task :default => :test
+
+Rake::TestTask.new do |test|
+  test.pattern = 'test/*_test.rb'
+  test.verbose = true
+end
+
+namespace :doc do
+  Rake::RDocTask.new do |rdoc|  
+    rdoc.rdoc_dir = 'doc'  
+    rdoc.title    = "AWS::S3 -- Support for Amazon S3's REST api"  
+    rdoc.options << '--line-numbers' << '--inline-source'
+    rdoc.rdoc_files.include('README')
+    rdoc.rdoc_files.include('lib/**/*.rb')
+  end
+  
+  task :rdoc => 'doc:readme'
+  
+  task :refresh => :rerdoc do
+    system 'open doc/index.html'
+  end
+
+  task :readme do
+    require 'support/rdoc/code_info'
+    RDoc::CodeInfo.parse('lib/**/*.rb')
+    
+    strip_comments = lambda {|comment| comment.gsub(/^# ?/, '')}
+    docs_for       = lambda do |location| 
+      info = RDoc::CodeInfo.for(location)
+      raise RuntimeError, "Couldn't find documentation for `#{location}'" unless info
+      strip_comments[info.comment]
+    end
+    
+    File.open('README', 'w') do |file|
+      file.write ERB.new(IO.read('README.erb')).result(binding)
+    end
+  end
+end
+
+namespace :dist do  
+  spec = Gem::Specification.new do |s|
+    s.name              = 'aws-s3'
+    s.version           = Gem::Version.new(AWS::S3::Version)
+    s.summary           = "Client library for Amazon's Simple Storage Service's REST API"
+    s.description       = s.summary
+    s.email             = 'marcel@vernix.org'
+    s.author            = 'Marcel Molina Jr.'
+    s.has_rdoc          = true
+    s.extra_rdoc_files  = %w(README COPYING INSTALL)
+    s.homepage          = 'http://amazon.rubyforge.org'
+    s.rubyforge_project = 'amazon'
+    s.files             = FileList['Rakefile', 'lib/**/*.rb', 'bin/*', 'support/**/*.rb']
+    s.executables       << 's3sh'
+    s.test_files        = Dir['test/**/*']
+    
+    s.add_dependency 'xml-simple'
+    s.add_dependency 'builder'
+    s.rdoc_options  = ['--title', "AWS::S3 -- Support for Amazon S3's REST api",
+                       '--main',  'README',
+                       '--line-numbers', '--inline-source']
+  end
+    
+  # Regenerate README before packaging
+  task :package => 'doc:readme'
+  Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_tar_gz = true
+    pkg.package_files.include('{lib,script,test,support}/**/*')
+    pkg.package_files.include('README')
+    pkg.package_files.include('COPYING')
+    pkg.package_files.include('INSTALL')
+    pkg.package_files.include('Rakefile')
+  end
+  
+  desc 'Install with gems'
+  task :install => :repackage do
+    sh "sudo gem i pkg/#{spec.name}-#{spec.version}.gem"
+  end
+  
+  desc 'Uninstall gem'
+  task :uninstall do
+    sh "sudo gem uninstall #{spec.name} -x"
+  end
+  
+  desc 'Reinstall gem'
+  task :reinstall => [:uninstall, :install]
+  
+  task :confirm_release do
+    print "Releasing version #{spec.version}. Are you sure you want to proceed? [Yn] "
+    abort if STDIN.getc == ?n
+  end
+  
+  desc 'Tag release'
+  task :tag do
+    svn_root = 'svn+ssh://marcel@rubyforge.org/var/svn/amazon/s3'
+    sh %(svn cp #{svn_root}/trunk #{svn_root}/tags/rel-#{spec.version} -m "Tag #{spec.name} release #{spec.version}")
+  end
+  
+  desc 'Update changelog to include a release marker'
+  task :add_release_marker_to_changelog do
+    changelog = IO.read('CHANGELOG')
+    changelog.sub!(/^trunk:/, "#{spec.version}:")
+    
+    File.open('CHANGELOG', 'w') do |file|
+      file.write "trunk:\n\n#{changelog}"
+    end
+  end
+  
+  task :commit_changelog do
+    sh %(svn ci CHANGELOG -m "Bump changelog version marker for release")
+  end
+  
+  desc 'Push a release to rubyforge'
+  task :release => [:confirm_release, :clean, :add_release_marker_to_changelog, :package, :commit_changelog, :tag] do 
+    require 'rubyforge'
+    package = File.join('pkg', "#{spec.name}-#{spec.version}")
+
+    rubyforge = RubyForge.new
+    rubyforge.login
+
+    version_already_released = lambda do
+      releases = rubyforge.config['rubyforge']['release_ids']
+      releases.has_key?(spec.name) && releases[spec.name][spec.version]
+    end
+    
+    abort("Release #{spec.version} already exists!") if version_already_released.call
+    
+    if release_id = rubyforge.add_release(spec.rubyforge_project, spec.name, spec.version, "#{package}.tar.gz")
+      rubyforge.add_file(spec.rubyforge_project, spec.name, release_id, "#{package}.gem")
+    else
+      puts 'Release failed!'
+    end
+  end
+  
+  task :spec do
+    puts spec.to_ruby
+  end
+end
+
+desc 'Check code to test ratio'
+task :stats do 
+  library_files = FileList["#{library_root}/lib/**/*.rb"]
+  test_files    = FileList["#{library_root}/test/**/*_test.rb"]
+  count_code_lines = Proc.new do |lines| 
+    lines.inject(0) do |code_lines, line|
+      next code_lines if [/^\s*$/, /^\s*#/].any? {|non_code_line| non_code_line === line}
+      code_lines + 1
+    end
+  end
+  
+  count_code_lines_for_files = Proc.new do |files|
+    files.inject(0) {|code_lines, file| code_lines + count_code_lines[IO.read(file)]}
+  end
+  
+  library_code_lines = count_code_lines_for_files[library_files]
+  test_code_lines    = count_code_lines_for_files[test_files]
+  ratio = Proc.new { sprintf('%.2f', test_code_lines.to_f / library_code_lines)}
+  
+  puts "Code LOC: #{library_code_lines}    Test LOC: #{test_code_lines}    Code to Test Ratio: 1:#{ratio.call}"
+end
+
+namespace :test do
+  desc 'Check test coverage'
+  task :coverage do
+    system("rcov --sort coverage #{File.join(library_root, 'test/*_test.rb')}")
+    show_test_coverage_results
+  end
+  
+  Rake::TestTask.new(:remote) do |test|
+    test.pattern = 'test/remote/*_test.rb'
+    test.verbose = true
+  end
+  
+  Rake::TestTask.new(:all) do |test|
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+
+  desc 'Check test coverage of full stack remote tests'
+  task :full_coverage do
+    system("rcov --sort coverage #{File.join(library_root, 'test/remote/*_test.rb')} #{File.join(library_root, 'test/*_test.rb')}")
+    show_test_coverage_results
+  end
+  
+  def show_test_coverage_results
+    system("open #{File.join(library_root, 'coverage/index.html')}") if PLATFORM['darwin']
+  end
+  
+  desc 'Remove coverage products'
+  task :clobber_coverage do
+    rm_r 'coverage' rescue nil
+  end
+end
+
+namespace :todo do
+  class << TODOS = IO.read(File.join(library_root, 'TODO'))
+    def items
+      split("\n").grep(/^\[\s|X\]/)
+    end
+    
+    def completed
+      find_items_matching(/^\[X\]/)
+    end
+    
+    def uncompleted
+      find_items_matching(/^\[\s\]/)
+    end
+        
+    def find_items_matching(regexp)
+      items.grep(regexp).instance_eval do
+        def display
+          puts map {|item| "* #{item.sub(/^\[[^\]]\]\s/, '')}"}
+        end
+        self
+      end
+    end
+  end
+  
+  desc 'Completed todo items'
+  task :completed do
+    TODOS.completed.display
+  end
+  
+  desc 'Incomplete todo items'
+  task :uncompleted do
+    TODOS.uncompleted.display
+  end
+end if File.exists?(File.join(library_root, 'TODO'))
+
+namespace :site do
+  require 'erb'
+  require 'rdoc/markup/simple_markup'
+  require 'rdoc/markup/simple_markup/to_html'
+  
+  readme    = lambda { IO.read('README')[/^== Getting started\n(.*)/m, 1] }
+  ruby_code = /^\s*\n(\s+\S+.*?)\n\s*\n/m
+
+  readme_to_html = lambda do
+    handler = SM::ToHtml.new
+    handler.instance_eval do
+      require 'syntax'
+      require 'syntax/convertors/html'
+      def accept_verbatim(am, fragment) 
+        syntax = Syntax::Convertors::HTML.for_syntax('ruby')
+        @res << %(<div class="ruby">#{syntax.convert(fragment.txt, true)}</div>)
+      end
+    end
+    SM::SimpleMarkup.new.convert(readme.call, handler)
+  end
+  
+  desc 'Regenerate the public website page'
+  task :build => 'doc:readme' do
+    File.open('site/public/index.html', 'w') do |file|
+      erb_data = {}
+      erb_data[:readme] = readme_to_html.call
+      file.write ERB.new(IO.read('site/index.erb')).result(binding)
+    end
+  end
+  
+  task :refresh => :build do
+    system 'open site/public/index.html'
+  end
+  
+  desc 'Update the live website'
+  task :deploy => :build do
+    site_files = FileList['site/public/*']
+    site_files.delete_if {|file| File.directory?(file)}
+    sh %(scp #{site_files.join ' '} marcel@rubyforge.org:/var/www/gforge-projects/amazon/)
+  end
+end 
+
+task :clean => ['dist:clobber_package', 'doc:clobber_rdoc', 'test:clobber_coverage']

data/bin/s3sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+s3_lib = File.dirname(__FILE__) + '/../lib/aws/s3'
+setup  = File.dirname(__FILE__) + '/setup'
+exec "irb -r #{s3_lib} -r #{setup} --simple-prompt"

data/bin/setup.rb

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+if ENV['AMAZON_ACCESS_KEY_ID'] && ENV['AMAZON_SECRET_ACCESS_KEY']
+  AWS::S3::Base.establish_connection!(
+    :access_key_id     => ENV['AMAZON_ACCESS_KEY_ID'], 
+    :secret_access_key => ENV['AMAZON_SECRET_ACCESS_KEY']
+  )
+end
+
+require File.dirname(__FILE__) + '/../test/fixtures'
+include AWS::S3

data/lib/aws/s3.rb

@@ -0,0 +1,64 @@
+require 'base64'
+require 'cgi'
+require 'uri'
+require 'openssl'
+require 'digest/sha1'
+require 'net/https'
+require 'time'
+require 'date'
+require 'generator'
+
+$:.unshift(File.dirname(__FILE__))
+require 's3/extensions'
+require_library_or_gem 'builder' unless defined? Builder
+
+require 's3/base'
+require 's3/version'
+require 's3/parsing'
+require 's3/acl'
+require 's3/logging'
+require 's3/bittorrent'
+require 's3/service'
+require 's3/owner'
+require 's3/bucket'
+require 's3/object'
+require 's3/error'
+require 's3/exceptions'
+require 's3/connection'
+require 's3/authentication'
+require 's3/response'
+
+AWS::S3::Base.class_eval do
+  include AWS::S3::Connection::Management
+end
+
+AWS::S3::Bucket.class_eval do
+  include AWS::S3::Logging::Management
+  include AWS::S3::ACL::Bucket
+end
+
+AWS::S3::S3Object.class_eval do
+  include AWS::S3::ACL::S3Object
+  include AWS::S3::BitTorrent
+end
+
+# XmlSimple is a very convenient way of dealing with the xml needs of this library, but unfortunately
+# it is powered by REXML which is both very slow (even for me who does not privilege performance)
+# and consumes way too much memory (beach balls a MacBookPro with 2GB of memory for 2 minutes while parsing 60KB of xml).
+#
+# So, if libxml is installed, we use the FasterXmlSimple library, that provides most of the functionality of XmlSimple
+# except it uses the xml/libxml library for xml parsing. If libxml isn't installed, we just fall back on
+# XmlSimple.
+AWS::S3::Parsing.parser = 
+  begin
+    # N.B. Push, don't shift
+    $:.push(File.join(File.dirname(__FILE__), '..', '..', 'support', 'faster-xml-simple', 'lib'))
+    require_library_or_gem 'faster_xml_simple'
+    # Older version of libxml aren't stable (bus error when requesting attributes that don't exist) so we
+    # have to use a version greater than '0.3.8.2'.
+    raise LoadError unless XML::Parser::VERSION > '0.3.8.2'
+    FasterXmlSimple
+  rescue LoadError
+    require_library_or_gem 'xmlsimple' unless defined? XmlSimple
+    XmlSimple
+  end

data/lib/aws/s3/acl.rb

@@ -0,0 +1,631 @@
+module AWS
+  module S3
+    # By default buckets are private. This means that only the owner has access rights to the bucket and its objects. 
+    # Objects in that bucket inherit the permission of the bucket unless otherwise specified. When an object is private, the owner can 
+    # generate a signed url that exposes the object to anyone who has that url. Alternatively, buckets and objects can be given other 
+    # access levels. Several canned access levels are defined:
+    # 
+    # * <tt>:private</tt> - Owner gets FULL_CONTROL. No one else has any access rights. This is the default.
+    # * <tt>:public_read</tt> - Owner gets FULL_CONTROL and the anonymous principal is granted READ access. If this policy is used on an object, it can be read from a browser with no authentication.
+    # * <tt>:public_read_write</tt> - Owner gets FULL_CONTROL, the anonymous principal is granted READ and WRITE access. This is a useful policy to apply to a bucket, if you intend for any anonymous user to PUT objects into the bucket.
+    # * <tt>:authenticated_read</tt> - Owner gets FULL_CONTROL, and any principal authenticated as a registered Amazon S3 user is granted READ access.
+    # 
+    # You can set a canned access level when you create a bucket or an object by using the <tt>:access</tt> option:
+    # 
+    #   S3Object.store(
+    #     'kiss.jpg', 
+    #     data, 
+    #     'marcel', 
+    #     :content_type => 'image/jpg', :access => :public_read
+    #   )
+    # 
+    # Since the image we created is publicly readable, we can access it directly from a browser by going to the corresponding bucket name 
+    # and specifying the object's key without a special authenticated url:
+    # 
+    #  http://s3.amazonaws.com/marcel/kiss.jpg
+    # 
+    # ==== Building costum access policies
+    # 
+    # For both buckets and objects, you can use the <tt>acl</tt> method to see its access control policy:
+    # 
+    #   policy = S3Object.acl('kiss.jpg', 'marcel')
+    #   pp policy.grants
+    #   [#<AWS::S3::ACL::Grant FULL_CONTROL to noradio>,
+    #    #<AWS::S3::ACL::Grant READ to AllUsers Group>]
+    # 
+    # Policies are made up of one or more grants which grant a specific permission to some grantee. Here we see the default FULL_CONTROL grant 
+    # to the owner of this object. There is also READ permission granted to the Allusers Group, which means anyone has read access for the object.
+    # 
+    # Say we wanted to grant access to anyone to read the access policy of this object. The current READ permission only grants them permission to read 
+    # the object itself (for example, from a browser) but it does not allow them to read the access policy. For that we will need to grant the AllUsers group the READ_ACP permission.
+    # 
+    # First we'll create a new grant object:
+    # 
+    #   grant = ACL::Grant.new
+    #   # => #<AWS::S3::ACL::Grant (permission) to (grantee)>
+    #   grant.permission = 'READ_ACP'
+    # 
+    # Now we need to indicate who this grant is for. In other words, who the grantee is:
+    # 
+    #   grantee = ACL::Grantee.new
+    #   # => #<AWS::S3::ACL::Grantee (xsi not set yet)>
+    # 
+    # There are three ways to specify a grantee: 1) by their internal amazon id, such as the one returned with an object's Owner, 
+    # 2) by their Amazon account email address or 3) by specifying a group. As of this writing you can not create custom groups, but 
+    # Amazon does provide three already: AllUsers, Authenticated and LogDelivery. In this case we want to provide the grant to all users. 
+    # This effectively means "anyone".
+    # 
+    #   grantee.group = 'AllUsers'
+    # 
+    # Now that our grantee is setup, we'll associate it with the grant:
+    # 
+    #   grant.grantee = grantee
+    #   grant
+    #   # => #<AWS::S3::ACL::Grant READ_ACP to AllUsers Group>
+    # 
+    # Are grant has all the information we need. Now that it's ready, we'll add it on to the object's access control policy's list of grants:
+    # 
+    #   policy.grants << grant
+    #   pp policy.grants
+    #   [#<AWS::S3::ACL::Grant FULL_CONTROL to noradio>,
+    #    #<AWS::S3::ACL::Grant READ to AllUsers Group>,
+    #    #<AWS::S3::ACL::Grant READ_ACP to AllUsers Group>]
+    # 
+    # Now that the policy has the new grant, we reuse the <tt>acl</tt> method to persist the policy change:
+    # 
+    #   S3Object.acl('kiss.jpg', 'marcel', policy)
+    # 
+    # If we fetch the object's policy again, we see that the grant has been added:
+    # 
+    #   pp S3Object.acl('kiss.jpg', 'marcel').grants
+    #   [#<AWS::S3::ACL::Grant FULL_CONTROL to noradio>,
+    #    #<AWS::S3::ACL::Grant READ to AllUsers Group>,
+    #    #<AWS::S3::ACL::Grant READ_ACP to AllUsers Group>]
+    # 
+    # If we were to access this object's acl url from a browser: 
+    # 
+    #   http://s3.amazonaws.com/marcel/kiss.jpg?acl
+    # 
+    # we would be shown its access control policy.
+    # 
+    # ==== Pre-prepared grants
+    # 
+    # Alternatively, the ACL::Grant class defines a set of stock grant policies that you can fetch by name. In most cases, you can 
+    # just use one of these pre-prepared grants rather than building grants by hand. Two of these stock policies are <tt>:public_read</tt> 
+    # and <tt>:public_read_acp</tt>, which happen to be the two grants that we built by hand above. In this case we could have simply written:
+    # 
+    #   policy.grants << ACL::Grant.grant(:public_read)
+    #   policy.grants << ACL::Grant.grant(:public_read_acp)
+    #   S3Object.acl('kiss.jpg', 'marcel', policy)
+    # 
+    # The full details can be found in ACL::Policy, ACL::Grant and ACL::Grantee.
+    module ACL
+      # The ACL::Policy class lets you inspect and modify access controls for buckets and objects.
+      # A policy is made up of one or more Grants which specify a permission and a Grantee to whom that permission is granted.
+      #
+      # Buckets and objects are given a default access policy which contains one grant permitting the owner of the bucket or object
+      # FULL_CONTROL over its contents. This means they can read the object, write to the object, as well as read and write its
+      # policy.
+      #
+      # The <tt>acl</tt> method for both buckets and objects returns the policy object for that entity:
+      #
+      #   policy = Bucket.acl('some-bucket')
+      #
+      # The <tt>grants</tt> method of a policy exposes its grants. You can treat this collection as an array and push new grants onto it:
+      #
+      #   policy.grants << grant
+      #
+      # Check the documentation for Grant and Grantee for more details on how to create new grants.
+      class Policy
+        include SelectiveAttributeProxy #:nodoc:
+        attr_accessor :owner, :grants
+        
+        def initialize(attributes = {})
+          @attributes = attributes
+          @grants     = [].extend(GrantListExtensions)
+          extract_owner!  if owner?
+          extract_grants! if grants?
+        end
+        
+        # The xml representation of the policy.
+        def to_xml
+          Builder.new(owner, grants).to_s
+        end
+        
+        private
+        
+          def owner?
+            attributes.has_key?('owner') || !owner.nil?
+          end
+          
+          def grants?
+            (attributes.has_key?('access_control_list') && attributes['access_control_list']['grant']) || !grants.empty?
+          end
+          
+          def extract_owner!
+            @owner = Owner.new(attributes.delete('owner'))
+          end
+          
+          def extract_grants!
+            attributes['access_control_list']['grant'].each do |grant|
+              grants << Grant.new(grant)
+            end
+          end
+          
+          module GrantListExtensions #:nodoc:
+            def include?(grant)
+              case grant
+              when Symbol
+                super(ACL::Grant.grant(grant))
+              else
+                super
+              end
+            end
+            
+            def delete(grant)
+              case grant
+              when Symbol
+                super(ACL::Grant.grant(grant))
+              else
+                super
+              end
+            end
+          end
+        
+        class Builder < XmlGenerator #:nodoc:
+          attr_reader :owner, :grants
+          def initialize(owner, grants)
+            @owner  = owner
+            @grants = grants.uniq # There could be some duplicate grants
+            super()
+          end
+      
+          def build
+            xml.tag!('AccessControlPolicy', 'xmlns' => 'http://s3.amazonaws.com/doc/2006-03-01/') do
+              xml.Owner do
+                xml.ID owner.id
+                xml.DisplayName owner.display_name
+              end
+              
+              xml.AccessControlList do
+                xml << grants.map {|grant| grant.to_xml}.join("\n")
+              end
+            end
+          end
+        end
+      end
+      
+      # A Policy is made up of one or more Grant objects. A grant sets a specific permission and grants it to the associated grantee.
+      #
+      # When creating a new grant to add to a policy, you need only set its permission and then associate with a Grantee.
+      #
+      #   grant = ACL::Grant.new
+      #   => #<AWS::S3::ACL::Grant (permission) to (grantee)>
+      #
+      # Here we see that neither the permission nor the grantee have been set. Let's make this grant provide the READ permission.
+      #
+      #   grant.permission = 'READ'
+      #   grant
+      #   => #<AWS::S3::ACL::Grant READ to (grantee)>
+      #
+      # Now let's assume we have a grantee to the AllUsers group already set up. Just associate that grantee with our grant. 
+      #
+      #   grant.grantee = all_users_group_grantee
+      #   grant
+      #   => #<AWS::S3::ACL::Grant READ to AllUsers Group>
+      #
+      # And now are grant is complete. It provides READ permission to the AllUsers group, effectively making this object publicly readable
+      # without any authorization.
+      #
+      # Assuming we have some object's policy available in a local variable called <tt>policy</tt>, we can now add this grant onto its
+      # collection of grants.
+      #
+      #   policy.grants << grant
+      #
+      # And then we send the updated policy to the S3 servers.
+      #
+      #   some_s3object.acl(policy)
+      class Grant
+        include SelectiveAttributeProxy #:nodoc:
+        constant :VALID_PERMISSIONS, %w(READ WRITE READ_ACP WRITE_ACP FULL_CONTROL)
+        attr_accessor :grantee
+        
+        class << self
+          # Returns stock grants with name <tt>type</tt>.
+          #
+          #   public_read_grant = ACL::Grant.grant :public_read
+          #   => #<AWS::S3::ACL::Grant READ to AllUsers Group>
+          #
+          # Valid stock grant types are:
+          #
+          # * <tt>:authenticated_read</tt>
+          # * <tt>:authenticated_read_acp</tt>
+          # * <tt>:authenticated_write</tt>
+          # * <tt>:authenticated_write_acp</tt>
+          # * <tt>:logging_read</tt>
+          # * <tt>:logging_read_acp</tt>
+          # * <tt>:logging_write</tt>
+          # * <tt>:logging_write_acp</tt>
+          # * <tt>:public_read</tt>
+          # * <tt>:public_read_acp</tt>
+          # * <tt>:public_write</tt>
+          # * <tt>:public_write_acp</tt>
+          def grant(type)
+            case type
+            when *stock_grant_map.keys
+              build_stock_grant_for type
+            else
+              raise ArgumentError, "Unknown grant type `#{type}'"
+            end
+          end
+          
+          private
+            def stock_grant_map
+              grant        = lambda {|permission, group| {:permission => permission, :group => group}}
+              groups       = {:public => 'AllUsers', :authenticated => 'Authenticated', :logging => 'LogDelivery'}
+              permissions  = %w(READ WRITE READ_ACP WRITE_ACP)
+              stock_grants = {}
+              groups.each do |grant_group_name, group_name|
+                permissions.each do |permission|
+                  stock_grants["#{grant_group_name}_#{permission.downcase}".to_sym] = grant[permission, group_name]
+                end
+              end
+              stock_grants
+            end
+            memoized :stock_grant_map
+            
+            def build_stock_grant_for(type)
+              stock_grant = stock_grant_map[type]
+              grant = new do |g|
+                g.permission = stock_grant[:permission]
+              end
+              grant.grantee = Grantee.new do |gr|
+                gr.group = stock_grant[:group]
+              end
+              grant
+            end
+        end
+        
+        def initialize(attributes = {})
+          attributes = {'permission' => nil}.merge(attributes)
+          @attributes = attributes
+          extract_grantee!
+          yield self if block_given?
+        end
+        
+        # Set the permission for this grant.
+        #
+        #   grant.permission = 'READ'
+        #   grant
+        #   => #<AWS::S3::ACL::Grant READ to (grantee)>
+        #
+        # If the specified permisison level is not valid, an <tt>InvalidAccessControlLevel</tt> exception will be raised.
+        def permission=(permission_level)
+          unless self.class.valid_permissions.include?(permission_level)
+            raise InvalidAccessControlLevel.new(self.class.valid_permissions, permission_level)
+          end
+          attributes['permission'] = permission_level
+        end
+        
+        # The xml representation of this grant.
+        def to_xml
+          Builder.new(permission, grantee).to_s
+        end
+        
+        def inspect #:nodoc:
+          "#<#{self.class}:##{object_id} #{self}>"
+        end
+        
+        def to_s #:nodoc:
+          [permission || '(permission)', 'to', grantee ? grantee.type_representation : '(grantee)'].join ' '
+        end
+        
+        def eql?(grant) #:nodoc:
+          # This won't work for an unposted AmazonCustomerByEmail because of the normalization
+          # to CanonicalUser but it will work for groups.
+          to_s == grant.to_s
+        end
+        alias_method :==, :eql?
+                
+        def hash #:nodoc:
+          to_s.hash
+        end
+        
+        private
+        
+          def extract_grantee!
+            @grantee = Grantee.new(attributes['grantee']) if attributes['grantee']
+          end
+          
+        class Builder < XmlGenerator #:nodoc:
+          attr_reader :grantee, :permission
+      
+          def initialize(permission, grantee)
+            @permission = permission
+            @grantee    = grantee
+            super()
+          end
+      
+          def build
+            xml.Grant do
+              xml << grantee.to_xml
+              xml.Permission permission
+            end
+          end
+        end
+      end
+      
+      # Grants bestow a access permission to grantees. Each grant of some access control list Policy is associated with a grantee.
+      # There are three ways of specifying a grantee at the time of this writing.
+      #
+      # * By canonical user - This format uses the <tt>id</tt> of a given Amazon account. The id value for a given account is available in the
+      #  Owner object of a bucket, object or policy.
+      #
+      #   grantee.id = 'bb2041a25975c3d4ce9775fe9e93e5b77a6a9fad97dc7e00686191f3790b13f1'
+      #
+      # Often the id will just be fetched from some owner object.
+      #
+      #   grantee.id = some_object.owner.id
+      # 
+      # * By amazon email address - You can specify an email address for any Amazon account. The Amazon account need not be signed up with the S3 service.
+      # though it must be unique across the entire Amazon system. This email address is normalized into a canonical user representation once the grant
+      # has been sent back up to the S3 servers.
+      #
+      #   grantee.email_address = 'joe@example.org'
+      #
+      # * By group - As of this writing you can not create custom groups, but Amazon provides three group that you can use. See the documentation for the
+      # Grantee.group= method for details.
+      #
+      #   grantee.group = 'Authenticated'
+      class Grantee
+        include SelectiveAttributeProxy #:nodoc:
+        
+        undef_method :id # Get rid of Object#id
+        
+        def initialize(attributes = {})
+          # Set default values for attributes that may not be passed in but we still want the object
+          # to respond to
+          attributes = {'id' => nil, 'display_name' => nil, 'email_address' => nil, 'uri' => nil}.merge(attributes)
+          @attributes = attributes
+          extract_type!
+          yield self if block_given?
+        end
+        
+        # The xml representation of the current grantee object.
+        def to_xml
+          Builder.new(self).to_s
+        end
+        
+        # Returns the type of grantee. Will be one of <tt>CanonicalUser</tt>, <tt>AmazonCustomerByEmail</tt> or <tt>Group</tt>.
+        def type
+          return attributes['type'] if attributes['type']
+          
+          # Lookups are in order of preference so if, for example, you set the uri but display_name and id are also
+          # set, we'd rather go with the canonical representation.
+          if display_name && id
+            'CanonicalUser'
+          elsif email_address
+            'AmazonCustomerByEmail'
+          elsif uri
+            'Group'
+          end
+        end
+        
+        # Sets the grantee's group by name.
+        #
+        #   grantee.group = 'AllUsers'
+        #
+        # Currently, valid groups defined by S3 are:
+        #
+        # * <tt>AllUsers</tt>: This group represents anyone. In other words, an anonymous request.
+        # * <tt>Authenticated</tt>: Any authenticated account on the S3 service.
+        # * <tt>LogDelivery</tt>: The entity that delivers bucket access logs.
+        def group=(group_name)
+          section  = %w(AllUsers Authenticated).include?(group_name) ? 'global' : 's3'
+          self.uri = "http://acs.amazonaws.com/groups/#{section}/#{group_name}"
+        end
+        
+        # Returns the grantee's group. If the grantee is not a group, <tt>nil</tt> is returned.
+        def group
+          return unless uri
+          uri[%r([^/]+$)]
+        end
+        
+        def type_representation #:nodoc:
+          case type
+          when 'CanonicalUser'          then display_name || id
+          when 'AmazonCustomerByEmail'  then email_address
+          when 'Group'                  then "#{group} Group"
+          end
+        end
+        
+        def inspect #:nodoc:
+          "#<#{self.class}:##{object_id} #{type_representation || '(xsi not set yet)'}>"
+        end
+        
+        private
+          def extract_type!
+            attributes['type'] = attributes.delete('xsi:type')
+          end            
+
+        class Builder < XmlGenerator #:nodoc:
+          
+          def initialize(grantee)
+            @grantee = grantee
+            super()
+          end
+          
+          def build
+            xml.tag!('Grantee', attributes) do
+              representation
+            end
+          end
+          
+          private
+            attr_reader :grantee
+            
+            def representation
+              case grantee.type
+              when 'CanonicalUser'
+                xml.ID grantee.id
+                xml.DisplayName grantee.display_name
+              when 'AmazonCustomerByEmail'
+                xml.EmailAddress grantee.email_address
+              when 'Group'
+                xml.URI grantee.uri
+              end
+            end
+            
+            def attributes
+              {'xsi:type' => grantee.type, 'xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance'}
+            end
+        end
+      end
+      
+      module Bucket
+        def self.included(klass) #:nodoc:
+          klass.extend(ClassMethods)
+        end
+        
+        module ClassMethods
+          # The acl method is the single point of entry for reading and writing access control list policies for a given bucket.
+          #   
+          #   # Fetch the acl for the 'marcel' bucket
+          #   policy = Bucket.acl 'marcel'
+          #
+          #   # Modify the policy ...
+          #   # ...
+          # 
+          #   # Send updated policy back to the S3 servers
+          #   Bucket.acl 'marcel', policy 
+          def acl(name = nil, policy = nil)
+            if name.is_a?(ACL::Policy)
+              policy = name
+              name   = nil
+            end
+
+            path = path(name) << '?acl'
+            respond_with ACL::Policy::Response do
+              policy ? put(path, {}, policy.to_xml) : ACL::Policy.new(get(path(name) << '?acl').policy)
+            end
+          end
+        end
+        
+        # The acl method returns and updates the acl for a given bucket.
+        #
+        #   # Fetch a bucket
+        #   bucket = Bucket.find 'marcel'
+        #
+        #   # Add a grant to the bucket's policy
+        #   bucket.acl.grants << some_grant
+        #
+        #   # Write the changes to the policy
+        #   bucket.acl(bucket.acl)
+        def acl(reload = false)
+          policy = reload.is_a?(ACL::Policy) ? reload : nil
+          memoize(reload) do
+            self.class.acl(name, policy) if policy
+            self.class.acl(name)
+          end
+        end
+      end
+      
+      module S3Object
+        def self.included(klass) #:nodoc:
+          klass.extend(ClassMethods)
+        end
+        
+        module ClassMethods
+          # The acl method is the single point of entry for reading and writing access control list policies for a given object.
+          #   
+          #   # Fetch the acl for the 'kiss.jpg' object in the 'marcel' bucket
+          #   policy = S3Object.acl 'kiss.jpg', 'marcel'
+          #
+          #   # Modify the policy ...
+          #   # ...
+          # 
+          #   # Send updated policy back to the S3 servers
+          #   S3Object.acl 'kiss.jpg', 'marcel', policy
+          def acl(name, bucket = nil, policy = nil)
+            # We're using the second argument as the ACL::Policy
+            if bucket.is_a?(ACL::Policy)
+              policy = bucket
+              bucket = nil
+            end
+
+            bucket = bucket_name(bucket)
+            path   = path!(bucket, name) << '?acl'
+
+            respond_with ACL::Policy::Response do
+              policy ? put(path, {}, policy.to_xml) : ACL::Policy.new(get(path).policy)
+            end
+          end
+        end
+        
+        # The acl method returns and updates the acl for a given s3 object.
+        #
+        #   # Fetch a the object
+        #   object = S3Object.find 'kiss.jpg', 'marcel'
+        #
+        #   # Add a grant to the object's
+        #   object.acl.grants << some_grant
+        #
+        #   # Write the changes to the policy
+        #   object.acl(object.acl)
+        def acl(reload = false)
+          policy = reload.is_a?(ACL::Policy) ? reload : nil
+          memoize(reload) do
+            self.class.acl(key, bucket.name, policy) if policy
+            self.class.acl(key, bucket.name)
+          end
+        end
+      end
+          
+      class OptionProcessor #:nodoc:
+        attr_reader :options
+        class << self
+          def process!(options)
+            new(options).process!
+          end
+        end
+
+        def initialize(options)
+          options.to_normalized_options!
+          @options      = options
+          @access_level = extract_access_level
+        end
+
+        def process!
+          return unless access_level_specified?
+          validate!
+          options['x-amz-acl'] = access_level
+        end
+
+        private
+          def extract_access_level
+             options.delete('access') || options.delete('x-amz-acl')
+          end
+
+          def validate!
+            raise InvalidAccessControlLevel.new(valid_levels, access_level) unless valid?
+          end
+
+          def valid?
+            valid_levels.include?(access_level)
+          end
+
+          def access_level_specified?
+            !@access_level.nil?
+          end
+
+          def valid_levels
+            %w(private public-read public-read-write authenticated-read)
+          end
+
+          def access_level
+            @normalized_access_level ||= @access_level.to_header
+          end
+      end
+    end
+  end
+end