s3lib 0.1.0

data/lib/bucket_create.rb

@@ -0,0 +1,39 @@
+# s3_bucket.rb
+require File.join(File.dirname(__FILE__), 's3_authenticator')
+module S3Lib
+  
+  class NotYourBucketError < S3Lib::S3ResponseError
+  end
+  
+  class Bucket
+  
+    # Todo:
+    # Class methods
+    # Bucket::find
+    # Bucket::delete (have :force => true)
+    # Bucket::delete_all_objects
+    # Bucket::objects
+    # Bucket::new
+    # instance methods
+    # Bucket#objects
+    # Bucket#delete
+    # Bucket#delete_all_objects
+    # Bucket#each
+  
+    def self.create(name, params = {})
+      params['x-amz-acl'] = params.delete(:access) if params[:access] # translate from :access to 'x-amz-acl'
+      begin
+        response = S3Lib.request(:put, name, params)
+      rescue S3Lib::S3ResponseError => error
+        if error.amazon_error_type == "BucketAlreadyExists"
+          raise S3Lib::NotYourBucketError.new("The bucket '#{name}' is already owned by somebody else", error.io, error.s3requester)
+        else
+          raise # re-raise the exception if it's not a BucketAlreadyExists error
+        end
+      end    
+      response.status[0] == "200" ? true : false
+    end
+  
+  end
+  
+end

data/lib/bucket_find.rb

@@ -0,0 +1,41 @@
+# s3_bucket.rb
+require File.join(File.dirname(__FILE__), 's3_authenticator')
+require 'rexml/document'
+
+module S3Lib
+  
+  class Bucket
+    
+    attr_reader :xml, :prefix, :marker, :max_keys
+    
+    def self.find(name, params = {})
+      response = S3Lib.request(:get, name)
+      doc = REXML::Document.new(response)
+      Bucket.new(doc)
+    end
+    
+    def initialize(doc)
+      @xml = doc.root
+      @name = @xml.elements['Name'].text
+      @max_keys = @xml.elements['MaxKeys'].text.to_i
+      @prefix = @xml.elements['Prefix'].text
+      @marker = @xml.elements['Marker'].text
+    end
+    
+    def is_truncated?
+      @xml.elements['IsTruncated'].text == 'true'
+    end
+    
+    def objects
+      REXML::XPath.match(@xml, '//Contents').collect do |object|
+        S3Lib::S3Object.new(object)
+      end
+    end
+    
+  end
+  
+end
+
+if __FILE__ == $0
+  S3Lib::Bucket.find('spatten_syncdemo')
+end

data/lib/bucket_with_acl_mixin.rb

@@ -0,0 +1,103 @@
+# bucket.rb
+module S3Lib
+    
+  class Bucket
+    
+    attr_reader :name, :xml, :prefix, :marker, :max_keys
+    
+    include S3Lib::AclAccess
+    
+    def self.create(name, params = {})
+      params['x-amz-acl'] = params.delete(:access) if params[:access] # translate from :access to 'x-amz-acl'
+      response = self.bucket_request(:put, name, params)
+      response.status[0] == "200" ? true : false
+    end
+    
+    # passing :force => true will cause the bucket to be deleted even if it is not empty.
+    def self.delete(name, params = {})
+      if params.delete(:force)
+        self.delete_all(name, params)
+      end
+      response = self.bucket_request(:delete, name, params)
+    end
+    
+    def delete(params = {})
+      self.class.delete(@name, @params.merge(params))
+    end
+    
+    def self.delete_all(name, params = {})
+      bucket = Bucket.find(name, params)
+      bucket.delete_all
+    end
+    
+    def delete_all
+      objects.each do |object|
+        object.delete
+      end
+    end
+
+    def self.find(name, params = {})
+      response = self.bucket_request(:get, name, params)
+      doc = REXML::Document.new(response)
+      Bucket.new(doc, params)
+    end
+    
+    def initialize(doc, params = {})
+      @xml = doc.root
+      @params = params
+      @name = @xml.elements['Name'].text
+      @max_keys = @xml.elements['MaxKeys'].text.to_i
+      @prefix = @xml.elements['Prefix'].text
+      @marker = @xml.elements['Marker'].text
+    end
+    
+    def is_truncated?
+      @xml.elements['IsTruncated'].text == 'true'
+    end
+    
+    def objects(params = {})
+      refresh if params[:refresh]
+      @objects || get_objects
+    end
+        
+    def refresh
+      refreshed_bucket = Bucket.find(@name, @params)
+      @xml = refreshed_bucket.xml
+      @objects = nil
+    end
+    
+    def url
+      @name
+    end
+    
+    # access an object in the bucket by key name
+    def [](key)
+      objects.detect{|object| object.key == key}
+    end
+    
+    private
+        
+    def self.bucket_request(verb, name, params = {})
+      begin
+        response = S3Lib.request(verb, name, params)  
+      rescue S3Lib::S3ResponseError => error
+        case error.amazon_error_type
+        when "NoSuchBucket": raise S3Lib::BucketNotFoundError.new("The bucket '#{name}' does not exist.", error.io, error.s3requester)
+        when "NotSignedUp": raise S3Lib::NotYourBucketError.new("The bucket '#{name}' is owned by someone else.", error.io, error.s3requester)
+        when "BucketNotEmpty": raise S3Lib::BucketNotEmptyError.new("The bucket '#{name}' is not empty, so you can't delete it.\nTry using Bucket.delete_all('#{name}') first, or Bucket.delete('#{name}', :force => true).", error.io, error.s3requester)
+        else # Re-raise the error if it's not one of the above
+          raise
+        end
+      end
+    end    
+    
+    def get_objects
+      @objects = REXML::XPath.match(@xml, '//Contents').collect do |object|
+        key = object.elements['Key'].text
+        S3Lib::S3Object.new(self, key, :lazy_load => true)
+      end
+    end
+    
+  end
+  
+end

data/lib/error_handling.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require File.join(File.dirname(__FILE__),'s3_authenticator')
+
+begin
+  req = S3Lib.request(:put, "spatten_sample_bucket/sample_object", :body => "Wheee")
+rescue S3Lib::S3ResponseError => e
+  puts "Amazon Error Type: #{e.amazon_error_type}"
+  puts "HTTP Status: #{e.status.join(',')}"
+  puts "Response from Amazon: #{e.response}"
+  puts "canonical string: #{e.s3requester.canonical_string}" if e.amazon_error_type == 'SignatureDoesNotMatch'
+end

data/lib/grant.rb

@@ -0,0 +1,107 @@
+module S3Lib
+  class Grant
+    attr_reader :acl, :grantee, :type, :permission
+    GRANT_TYPES = {:canonical => 'CanonicalUser',
+                   :email => 'AmazonCustomerByEmail', 
+                   :all_s3 => 'Group', 
+                   :public => 'Group'}
+    GROUP_URIS = {'http://acs.amazonaws.com/groups/global/AuthenticatedUsers' => :all_s3,
+                  'http://acs.amazonaws.com/groups/global/AllUsers' => :public}
+    PERMISSIONS = [:read, :write, :read_acl, :write_acl, :full_control]
+    NAMESPACE_URI = 'http://www.w3.org/2001/XMLSchema-instance'
+    
+    # Create a new grant.  
+    # permission is one of the PERMISSIONS defined above
+    # grantee can be either a REXML::Document object or a Hash
+    # The grantee Hash should look like this:
+    # {:type => :canonical|:email|:all_s3|:public, 
+    #  :grantee => canonical_user_id | email_address}
+    #
+    # The :grantee element of the hash is only required (and meaningful) 
+    # for :canonical and :email Grants
+    def initialize(permission, grantee)
+      @type = parse_type(grantee)
+      @permission = parse_permission(permission)
+      @grantee = parse_grantee(grantee)
+    end
+    
+    def to_xml
+      builder = Builder::XmlMarkup.new(:indent => 2)
+      xml = builder.Grant do
+        builder.Grantee('xmlns:xsi' => NAMESPACE_URI, 'xsi:type' => GRANT_TYPES[@type]) do
+          case type
+          when :canonical: builder.ID(@grantee)
+          when :email: builder.EmailAddress(@grantee)
+          when :all_s3: builder.URI(group_uri_from_group_type(:all_s3))
+          when :public: builder.URI(group_uri_from_group_type(:public))
+          else
+          end
+        end
+        builder.Permission(@permission.to_s.upcase)
+      end
+    end
+    
+    def inspect
+      "#{@permission} to #{@type}#{" #{@grantee}" if [:email, :canonical].include?(@type)}"
+    end
+    
+    private
+    
+    # permission can either be the String provided by S3
+    # or a symbol (see the PERMISSIONS array for allowed values)
+    def parse_permission(permission)
+      if permission.is_a?(String)
+        permission.downcase.to_sym
+      else
+        permission
+      end
+    end
+    
+    def parse_type(grantee)
+      if grantee.is_a?(Hash)
+        grantee[:type]
+      else # Assume it's a REXML::Doc object
+        type = grantee.attributes['xsi:type']
+        case type
+        when 'CanonicalUser': :canonical
+        when 'AmazonCustomerByEmail': :email
+        when 'Group'
+          group_uri = grantee.elements['URI'].text
+          group_type_from_group_uri(group_uri)
+        else
+          raise BadGrantTypeError
+        end
+      end
+    end
+    
+    def parse_grantee(grantee)
+      if grantee.is_a?(Hash) 
+        if [:canonical, :email].include?(@type)
+          grantee[:grantee]
+        else
+          @type
+        end
+      else # it's a REXML::Doc object
+        case @type
+        when :canonical
+          grantee.elements['ID'].text
+        when :email
+          grantee.elements['EmailAddress'].text
+        when :all_s3: :all_s3
+        when :public: :public
+        else
+          nil
+        end
+      end
+    end
+    
+    def group_type_from_group_uri(group_uri)
+      GROUP_URIS[group_uri]
+    end
+    
+    def group_uri_from_group_type(group_type)
+      GROUP_URIS.invert[group_type]
+    end
+    
+  end
+end

data/lib/grant_creating_a_grant_recipe.rb

@@ -0,0 +1,103 @@
+module S3Lib
+  class Grant
+    attr_reader :acl, :grantee, :type, :permission
+    GRANT_TYPES = {:canonical => 'CanonicalUser',
+                   :email => 'AmazonCustomerByEmail', 
+                   :all_s3 => 'Group', 
+                   :public => 'Group'}
+    GROUP_URIS = {'http://acs.amazonaws.com/groups/global/AuthenticatedUsers' => :all_s3,
+                  'http://acs.amazonaws.com/groups/global/AllUsers' => :public}
+    PERMISSIONS = [:read, :write, :read_acl, :write_acl, :full_control]
+    NAMESPACE_URI = 'http://www.w3.org/2001/XMLSchema-instance'
+    
+    # Create a new grant.  
+    # permission is one of the PERMISSIONS defined above
+    # grantee can be either a REXML::Document object or a Hash
+    # The grantee Hash should look like this:
+    # {:type => :canonical|:email|:all_s3|:public, 
+    #  :grantee => canonical_user_id | email_address}
+    #
+    # The :grantee element of the hash is only required (and meaningful) 
+    # for :canonical and :email Grants
+    def initialize(permission, grantee)
+      @type = parse_type(grantee)
+      @permission = parse_permission(permission)
+      @grantee = parse_grantee(grantee)
+    end
+    
+    def to_xml
+      builder = Builder::XmlMarkup.new(:indent => 2)
+      xml = builder.Grant do
+        builder.Grantee('xmlns:xsi' => NAMESPACE_URI, 'xsi:type' => GRANT_TYPES[@type]) do
+          case type
+          when :canonical: builder.ID(@grantee)
+          when :email: builder.EmailAddress(@grantee)
+          when :all_s3: builder.URI(group_uri_from_group_type(:all_s3))
+          when :public: builder.URI(group_uri_from_group_type(:public))
+          else
+          end
+        end
+        builder.Permission(@permission.to_s.upcase)
+      end
+    end
+    
+    private
+    
+    # permission can either be the String provided by S3
+    # or a symbol (see the PERMISSIONS array for allowed values)
+    def parse_permission(permission)
+      if permission.is_a?(String)
+        permission.downcase.to_sym
+      else
+        permission
+      end
+    end
+    
+    def parse_type(grantee)
+      if grantee.is_a?(Hash)
+        grantee[:type]
+      else # Assume it's a REXML::Doc object
+        type = grantee.attributes['xsi:type']
+        case type
+        when 'CanonicalUser': :canonical
+        when 'AmazonCustomerByEmail': :email
+        when 'Group'
+          group_uri = grantee.elements['URI'].text
+          group_type_from_group_uri(group_uri)
+        else
+          raise BadGrantTypeError
+        end
+      end
+    end
+    
+    def parse_grantee(grantee)
+      if grantee.is_a?(Hash) 
+        if [:canonical, :email].include?(@type)
+          grantee[:grantee]
+        else
+          @type
+        end
+      else # it's a REXML::Doc object
+        case @type
+        when :canonical
+          grantee.elements['ID'].text
+        when :email
+          grantee.elements['EmailAddress'].text
+        when :all_s3: :all_s3
+        when :public: :public
+        else
+          nil
+        end
+      end
+    end
+    
+    def group_type_from_group_uri(group_uri)
+      GROUP_URIS[group_uri]
+    end
+    
+    def group_uri_from_group_type(group_type)
+      GROUP_URIS.invert[group_type]
+    end
+    
+  end
+end

data/lib/grant_reading_acl_recipe.rb

@@ -0,0 +1,51 @@
+module S3Lib
+  class Grant
+    attr_reader :acl, :grantee, :type, :permission
+    GRANT_TYPES = {:canonical => 'CanonicalUser',
+                   :email => 'AmazonCustomerByEmail', 
+                   :all_s3 => 'Group', 
+                   :public => 'Group'}
+    GROUP_URIS = {'http://acs.amazonaws.com/groups/global/AuthenticatedUsers' => :all_s3,
+                  'http://acs.amazonaws.com/groups/global/AllUsers' => :public}
+    PERMISSIONS = [:read, :write, :read_acl, :write_acl, :full_control]
+    NAMESPACE_URI = 'http://www.w3.org/2001/XMLSchema-instance'
+    
+    # Create a new grant.  
+    # permission is one of the PERMISSIONS defined above
+    # grantee is the REXML::Document Grantee object returned by S3
+    def initialize(permission, grantee)
+      @permission = permission.downcase.to_sym      
+      @type = parse_type(grantee)
+      @grantee = parse_grantee(grantee)
+    end
+    
+    private
+    
+    def parse_type(grantee)
+      type = grantee.attributes['xsi:type']
+      case type
+      when 'CanonicalUser': :canonical
+      when 'AmazonCustomerByEmail': :email
+      when 'Group'
+        group_uri = grantee.elements['URI'].text
+        GROUP_URIS[group_uri]
+      else
+        raise BadGrantTypeError        
+      end
+    end
+    
+    def parse_grantee(grantee)
+      case @type
+      when :canonical
+        grantee.elements['ID'].text
+      when :email
+        grantee.elements['EmailAddress'].text
+      when :all_s3: :all_s3
+      when :public: :public
+      else
+        nil
+      end
+    end
+    
+  end
+end

data/lib/object.rb

@@ -0,0 +1,144 @@
+# s3_object.rb
+
+module S3Lib
+
+  class S3Object
+    
+    DEFAULT_CONTENT_TYPE = 'binary/octect-stream'
+    
+    attr_reader :key, :bucket
+        
+    # This is just an alias for S3Object.new
+    def self.find(bucket, key, options = {})
+      S3Object.new(bucket, key, options)
+    end
+    
+    def self.create(bucket, key, value = "", options = {})    
+			# translate from :access to 'x-amz-acl'
+      options['x-amz-acl'] = options.delete(:access) if options[:access]   
+      options['content-type'] ||= DEFAULT_CONTENT_TYPE
+      options[:body] = value || ""
+
+      response = S3Object.object_request(:put, S3Object.url(bucket, key), options)
+      response.status[0] == "200" ? S3Object.new(bucket, key, options) : false
+    end
+    
+    # Delete an object given the object's bucket and key.
+    # No error will be raised if the object does not exist.
+    def self.delete(bucket, key, options = {})
+      S3Object.object_request(:delete, S3Object.url(bucket, key), options)
+    end
+    
+    def delete
+      S3Object.delete(@bucket, @key, @options)
+    end
+    
+    def self.value(bucket, key, options = {})
+      request = S3Object.object_request(:get, S3Object.url(bucket, key), options)      
+      request.read
+    end
+    
+    # Both metadata and value are loaded lazily if options[:lazy_load] is true
+    # This is used by Bucket.find so you don't make a request for every object in the bucket
+    # The bucket can be either a bucket object or a string containing the bucket's name
+    # The key is a string.
+    def initialize(bucket, key, options = {})
+      bucket = Bucket.find(bucket) unless bucket.respond_to?(:name)
+      @bucket = bucket
+      @key = key
+      @options = options
+      get_metadata unless options[:lazy_load]
+    end  
+    
+    # bucket can be either a Bucket object or a string containing the bucket's name
+    def self.url(bucket, key)
+      bucket_name = bucket.respond_to?(:name) ? bucket.name : bucket
+      File.join(bucket_name, key)
+    end     
+    
+    def url
+      S3Object.url(@bucket.name, @key)
+    end 
+    
+    def metadata
+      @metadata || get_metadata
+    end
+    
+    def value(params = {})
+      refresh if params[:refresh]
+      @value || get_value
+    end
+    
+    def value=(value)
+      S3Object.create(@bucket, @key, value, @options)
+      @value = value
+      refresh_metadata
+    end
+    
+    def refresh
+      get_value
+    end
+    
+    def refresh_metadata
+      get_metadata
+    end
+    
+    def refresh_acl
+      get_acl
+    end
+    
+    def content_type
+      metadata["content-type"]
+    end
+    
+    # strip off the leading and trailing double-quotes
+    def etag
+      metadata["etag"].sub(/\A\"/,'').sub(/\"\Z/, '')
+    end
+    
+    def length
+      metadata["content-length"].to_i
+    end
+    
+    def acl(params = {})
+      refresh_acl if params[:refresh]      
+      @acl || get_acl
+    end  
+    
+    private
+    
+    def self.object_request(verb, url, options = {})
+      begin
+        options.delete(:lazy_load)
+        response = S3Lib.request(verb, url, options)
+      rescue S3Lib::S3ResponseError => error
+        case error.amazon_error_type
+        when 'NoSuchBucket': raise S3Lib::BucketNotFoundError.new("The bucket '#{bucket}' does not exist.", error.io, error.s3requester)
+        when 'NotSignedUp': raise S3Lib::NotYourBucketError.new("The bucket '#{bucket}' is owned by somebody else", error.io, error.s3requester)
+        when 'AccessDenied': raise S3Lib::NotYourBucketError.new("The bucket '#{bucket}' is owned by someone else.", error.io, error.s3requester)
+        when 'MissingContentLength': raise S3Lib::NoContentError.new("You must provide a value to put in the object.\nUsage: S3Lib::S3Object.create(bucket, key, value, options)", error.io, error.s3requester)          
+        else # Re-raise the error if it's not one of the above
+          raise
+        end
+      end
+      response
+    end
+        
+    def get_metadata
+      request = S3Object.object_request(:head, url, @options)
+      @metadata = request.meta
+    end
+    
+    def get_value
+      request = S3Object.object_request(:get, url, @options)
+      @metadata = request.meta      
+      @value = request.read
+    end
+    
+    def get_acl
+      @acl = Acl.new(self)
+    end    
+    
+  end
+
+end

data/lib/object_from_bucket_test.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+require File.join(File.dirname(__FILE__), 'object')
+require 'rexml/document'
+require 'pp'
+
+bucket_request = S3Lib.request(:get, 'spatten_syncdemo')
+bucket_doc = REXML::Document.new(bucket_request.read)
+first_object = REXML::XPath.match(bucket_doc, "//Contents").first
+
+# puts first_object
+
+puts "from bucket xml:"
+pp first_object.to_hash
+
+puts "from get on object:"
+object = S3Lib.request(:get, 'spatten_syncdemo/flowers.jpg')
+pp object.meta