aws-s3-instructure 0.6.2.1319222580

data/lib/aws/s3/error.rb

@@ -0,0 +1,69 @@
+module AWS
+  module S3
+    # Anything you do that makes a request to S3 could result in an error. If it does, the AWS::S3 library will raise an exception 
+    # specific to the error. All exception that are raised as a result of a request returning an error response inherit from the 
+    # ResponseError exception. So should you choose to rescue any such exception, you can simple rescue ResponseError. 
+    # 
+    # Say you go to delete a bucket, but the bucket turns out to not be empty. This results in a BucketNotEmpty error (one of the many 
+    # errors listed at http://docs.amazonwebservices.com/AmazonS3/2006-03-01/ErrorCodeList.html):
+    # 
+    #   begin
+    #     Bucket.delete('jukebox')
+    #   rescue ResponseError => error
+    #     # ...
+    #   end
+    # 
+    # Once you've captured the exception, you can extract the error message from S3, as well as the full error response, which includes 
+    # things like the HTTP response code:
+    # 
+    #   error
+    #   # => #<AWS::S3::BucketNotEmpty The bucket you tried to delete is not empty>
+    #   error.message
+    #   # => "The bucket you tried to delete is not empty"
+    #   error.response.code
+    #   # => 409
+    # 
+    # You could use this information to redisplay the error in a way you see fit, or just to log the error and continue on.
+    class Error
+      #:stopdoc:
+      attr_accessor :response
+      def initialize(error, response = nil)
+        @error     = error
+        @response  = response
+        @container = AWS::S3
+        find_or_create_exception!
+      end
+      
+      def raise
+        Kernel.raise exception.new(message, response)
+      end
+      
+      private
+        attr_reader :error, :exception, :container
+        
+        def find_or_create_exception!
+          @exception = container.const_defined?(code) ? find_exception : create_exception
+        end
+        
+        def find_exception
+          exception_class = container.const_get(code)
+          Kernel.raise ExceptionClassClash.new(exception_class) unless exception_class.ancestors.include?(ResponseError)
+          exception_class
+        end
+        
+        def create_exception
+          container.const_set(code, Class.new(ResponseError))
+        end
+        
+        def method_missing(method, *args, &block)
+          # We actually want nil if the attribute is nil. So we use has_key? rather than [] + ||.
+          if error.has_key?(method.to_s)
+            error[method.to_s]
+          else
+            super
+          end
+        end
+    end
+  end
+end
+#:startdoc:

data/lib/aws/s3/exceptions.rb

@@ -0,0 +1,133 @@
+module AWS
+  module S3
+    
+    # Abstract super class of all AWS::S3 exceptions
+    class S3Exception < StandardError
+    end
+    
+    # All responses with a code between 300 and 599 that contain an <Error></Error> body are wrapped in an
+    # ErrorResponse which contains an Error object. This Error class generates a custom exception with the name
+    # of the xml Error and its message. All such runtime generated exception classes descend from ResponseError
+    # and contain the ErrorResponse object so that all code that makes a request can rescue ResponseError and get
+    # access to the ErrorResponse.
+    class ResponseError < S3Exception
+      attr_reader :response
+      def initialize(message, response)
+        @response = response
+        super(message)
+      end
+    end
+    
+    #:stopdoc:
+    
+    # Most ResponseError's are created just time on a need to have basis, but we explicitly define the
+    # InternalError exception because we want to explicitly rescue InternalError in some cases.
+    class InternalError < ResponseError
+    end
+    
+    class NoSuchKey < ResponseError
+    end
+    
+    class RequestTimeout < ResponseError
+    end
+    
+    # Abstract super class for all invalid options.
+    class InvalidOption < S3Exception
+    end
+    
+    # Raised if an invalid value is passed to the <tt>:access</tt> option when creating a Bucket or an S3Object.
+    class InvalidAccessControlLevel < InvalidOption
+      def initialize(valid_levels, access_level)
+        super("Valid access control levels are #{valid_levels.inspect}. You specified `#{access_level}'.")
+      end
+    end
+    
+    # Raised if either the access key id or secret access key arguments are missing when establishing a connection.
+    class MissingAccessKey < InvalidOption
+      def initialize(missing_keys)
+        key_list = missing_keys.map {|key| key.to_s}.join(' and the ')
+        super("You did not provide both required access keys. Please provide the #{key_list}.")
+      end
+    end
+    
+    # Raised if a request is attempted before any connections have been established.
+    class NoConnectionEstablished < S3Exception
+    end
+    
+    # Raised if an unrecognized option is passed when establishing a connection.
+    class InvalidConnectionOption < InvalidOption
+      def initialize(invalid_options)
+        message = "The following connection options are invalid: #{invalid_options.join(', ')}. "    +
+                  "The valid connection options are: #{Connection::Options::VALID_OPTIONS.join(', ')}."
+        super(message)
+      end
+    end
+    
+    # Raised if an invalid bucket name is passed when creating a new Bucket.
+    class InvalidBucketName < S3Exception
+      def initialize(invalid_name)
+        message = "`#{invalid_name}' is not a valid bucket name. "      + 
+                  "Bucket names must be between 3 and 255 bytes and "   +
+                  "can contain letters, numbers, dashes and underscores."
+        super(message)
+      end
+    end
+    
+    # Raised if an invalid key name is passed when creating an S3Object.
+    class InvalidKeyName < S3Exception
+      def initialize(invalid_name)
+        message = "`#{invalid_name}' is not a valid key name. "   + 
+                  "Key names must be no more than 1024 bytes long."
+        super(message)
+      end
+    end
+    
+    # Raised if an invalid value is assigned to an S3Object's specific metadata name.
+    class InvalidMetadataValue < S3Exception
+      def initialize(invalid_names)
+        message = "The following metadata names have invalid values: #{invalid_names.join(', ')}. " +
+                  "Metadata can not be larger than 2kilobytes."
+        super(message)
+      end
+    end
+    
+    # Raised if the current bucket can not be inferred when not explicitly specifying the target bucket in the calling
+    # method's arguments.
+    class CurrentBucketNotSpecified < S3Exception
+      def initialize(address)
+        message = "No bucket name can be inferred from your current connection's address (`#{address}')"
+        super(message)
+      end
+    end
+    
+    # Raised when an orphaned S3Object belonging to no bucket tries to access its (non-existant) bucket.
+    class NoBucketSpecified < S3Exception
+      def initialize
+        super('The current object must have its bucket set')
+      end
+    end
+    
+    # Raised if an attempt is made to save an S3Object that does not have a key set.
+    class NoKeySpecified < S3Exception
+      def initialize
+        super('The current object must have its key set')
+      end
+    end
+    
+    # Raised if you try to save a deleted object.
+    class DeletedObject < S3Exception
+      def initialize
+        super('You can not save a deleted object')
+      end
+    end
+    
+    class ExceptionClassClash < S3Exception #:nodoc:
+      def initialize(klass)
+        message = "The exception class you tried to create (`#{klass}') exists and is not an exception"
+        super(message)
+      end
+    end
+    
+    #:startdoc:
+  end
+end

data/lib/aws/s3/extensions.rb

@@ -0,0 +1,356 @@
+#:stopdoc:
+
+class Hash
+  def to_query_string(include_question_mark = true)
+    query_string = ''
+    unless empty?
+      query_string << '?' if include_question_mark
+      query_string << inject([]) do |params, (key, value)| 
+        params << "#{key}=#{value}" 
+      end.join('&')
+    end
+    query_string
+  end
+  
+  def to_normalized_options
+    # Convert all option names to downcased strings, and replace underscores with hyphens
+    inject({}) do |normalized_options, (name, value)|
+      normalized_options[name.to_header] = value.to_s
+      normalized_options
+    end
+  end
+  
+  def to_normalized_options!
+    replace(to_normalized_options)
+  end
+end
+
+class String
+  if RUBY_VERSION <= '1.9'
+    def previous!
+      self[-1] -= 1
+      self
+    end
+  else
+    def previous!
+      self[-1] = (self[-1].ord - 1).chr
+      self
+    end
+  end
+  
+  def previous
+    dup.previous!
+  end
+  
+  def to_header
+    downcase.tr('_', '-')
+  end
+  
+  # ActiveSupport adds an underscore method to String so let's just use that one if
+  # we find that the method is already defined
+  def underscore
+    gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").downcase
+  end unless public_method_defined? :underscore
+
+  if RUBY_VERSION >= '1.9'
+    def valid_utf8?
+      dup.force_encoding('UTF-8').valid_encoding?
+    end
+  else
+    def valid_utf8?
+      scan(Regexp.new('[^\x00-\xa0]', nil, 'u')) { |s| s.unpack('U') }
+      true
+    rescue ArgumentError
+      false
+    end
+  end
+  
+  # All paths in in S3 have to be valid unicode so this takes care of 
+  # cleaning up any strings that aren't valid utf-8 according to String#valid_utf8?
+  if RUBY_VERSION >= '1.9'
+    def remove_extended!
+      sanitized_string = ''
+      each_byte do |byte|
+        character = byte.chr
+        sanitized_string << character if character.ascii_only?
+      end
+      sanitized_string
+    end
+  else
+    def remove_extended!
+      gsub!(/[\x80-\xFF]/) { "%02X" % $&[0] }
+    end
+  end
+  
+  def remove_extended
+    dup.remove_extended!
+  end
+end
+
+class CoercibleString < String
+  class << self
+    def coerce(string)
+      new(string).coerce
+    end
+  end
+  
+  def coerce
+    case self
+    when 'true';         true
+    when 'false';         false
+    # Don't coerce numbers that start with zero
+    when  /^[1-9]+\d*$/;   Integer(self)
+    when datetime_format; Time.parse(self)
+    else
+      self
+    end
+  end
+  
+  private
+    # Lame hack since Date._parse is so accepting. S3 dates are of the form: '2006-10-29T23:14:47.000Z'
+    # so unless the string looks like that, don't even try, otherwise it might convert an object's
+    # key from something like '03 1-2-3-Apple-Tree.mp3' to Sat Feb 03 00:00:00 CST 2001.
+    def datetime_format
+      /^\d{4}-\d{2}-\d{2}\w\d{2}:\d{2}:\d{2}/
+    end
+end
+
+class Symbol
+  def to_header
+    to_s.to_header
+  end
+end
+
+module Kernel
+  def __method__(depth = 0)
+    caller[depth][/`([^']+)'/, 1]
+  end if RUBY_VERSION <= '1.8.7'
+  
+  def __called_from__
+    caller[1][/`([^']+)'/, 1]
+  end if RUBY_VERSION > '1.8.7'
+  
+  def expirable_memoize(reload = false, storage = nil)
+    current_method = RUBY_VERSION > '1.8.7' ? __called_from__ : __method__(1)
+    storage = "@#{storage || current_method}"
+    if reload 
+      instance_variable_set(storage, nil)
+    else
+      if cache = instance_variable_get(storage)
+        return cache
+      end
+    end
+    instance_variable_set(storage, yield)
+  end
+
+  def require_library_or_gem(library, gem_name = nil)
+    if RUBY_VERSION >= '1.9'
+      gem(gem_name || library, '>=0') 
+    end
+    require library
+  rescue LoadError => library_not_installed
+    begin
+      require 'rubygems'
+      require library
+    rescue LoadError
+      raise library_not_installed
+    end
+  end
+end
+
+class Object
+  def returning(value)
+    yield(value)
+    value
+  end
+end
+
+class Module
+  def memoized(method_name)
+    original_method = "unmemoized_#{method_name}_#{Time.now.to_i}"
+    alias_method original_method, method_name
+    module_eval(<<-EVAL, __FILE__, __LINE__)
+      def #{method_name}(reload = false, *args, &block)
+        expirable_memoize(reload) do
+          send(:#{original_method}, *args, &block)
+        end
+      end
+    EVAL
+  end
+  
+  def constant(name, value)
+    unless const_defined?(name)
+      const_set(name, value) 
+      module_eval(<<-EVAL, __FILE__, __LINE__)
+        def self.#{name.to_s.downcase}
+          #{name.to_s}
+        end
+      EVAL
+    end
+  end
+  
+  # Transforms MarcelBucket into
+  #
+  #   class MarcelBucket < AWS::S3::Bucket
+  #     set_current_bucket_to 'marcel'
+  #   end
+  def const_missing_from_s3_library(sym)
+    if sym.to_s =~ /^(\w+)(Bucket|S3Object)$/
+      const = const_set(sym, Class.new(AWS::S3.const_get($2)))
+      const.current_bucket = $1.underscore
+      const
+    else
+      const_missing_not_from_s3_library(sym)
+    end
+  end
+  alias_method :const_missing_not_from_s3_library, :const_missing
+  alias_method :const_missing, :const_missing_from_s3_library
+end
+
+
+class Class # :nodoc:
+  def cattr_reader(*syms)
+    syms.flatten.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__)
+        unless defined? @@#{sym}
+          @@#{sym} = nil
+        end
+
+        def self.#{sym}
+          @@#{sym}
+        end
+
+        def #{sym}
+          @@#{sym}
+        end
+      EOS
+    end
+  end
+
+  def cattr_writer(*syms)
+    syms.flatten.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__)
+        unless defined? @@#{sym}
+          @@#{sym} = nil
+        end
+
+        def self.#{sym}=(obj)
+          @@#{sym} = obj
+        end
+
+        def #{sym}=(obj)
+          @@#{sym} = obj
+        end
+      EOS
+    end
+  end
+
+  def cattr_accessor(*syms)
+    cattr_reader(*syms)
+    cattr_writer(*syms)
+  end
+end if Class.instance_methods(false).grep(/^cattr_(?:reader|writer|accessor)$/).empty?
+
+module SelectiveAttributeProxy
+  def self.included(klass)
+    klass.extend(ClassMethods)
+    klass.class_eval(<<-EVAL, __FILE__, __LINE__)
+      cattr_accessor :attribute_proxy
+      cattr_accessor :attribute_proxy_options
+      
+      # Default name for attribute storage
+      self.attribute_proxy         = :attributes
+      self.attribute_proxy_options = {:exclusively => true}
+      
+      private
+        # By default proxy all attributes
+        def proxiable_attribute?(name)
+          return true unless self.class.attribute_proxy_options[:exclusively]
+          send(self.class.attribute_proxy).has_key?(name)
+        end
+        
+        def method_missing(method, *args, &block)
+          # Autovivify attribute storage
+          if method == self.class.attribute_proxy
+            ivar = "@\#{method}"
+            instance_variable_set(ivar, {}) unless instance_variable_get(ivar).is_a?(Hash)
+            instance_variable_get(ivar)
+          # Delegate to attribute storage
+          elsif method.to_s =~ /^(\\w+)(=?)$/ && proxiable_attribute?($1)
+            attributes_hash_name = self.class.attribute_proxy
+            $2.empty? ? send(attributes_hash_name)[$1] : send(attributes_hash_name)[$1] = args.first
+          else
+            super
+          end
+        end
+    EVAL
+  end
+  
+  module ClassMethods
+    def proxy_to(attribute_name, options = {})
+      if attribute_name.is_a?(Hash)
+        options = attribute_name
+      else
+        self.attribute_proxy = attribute_name
+      end
+      self.attribute_proxy_options = options
+    end
+  end
+end
+
+# When streaming data up, Net::HTTPGenericRequest hard codes a chunk size of 1k. For large files this
+# is an unfortunately low chunk size, so here we make it use a much larger default size and move it into a method
+# so that the implementation of send_request_with_body_stream doesn't need to be changed to change the chunk size (at least not anymore
+# than I've already had to...).
+module Net
+  class HTTPGenericRequest
+    def send_request_with_body_stream(sock, ver, path, f)
+      raise ArgumentError, "Content-Length not given and Transfer-Encoding is not `chunked'" unless content_length() or chunked?
+      unless content_type()
+        warn 'net/http: warning: Content-Type did not set; using application/x-www-form-urlencoded' if $VERBOSE
+        set_content_type 'application/x-www-form-urlencoded'
+      end
+      write_header sock, ver, path
+      if chunked?
+        while s = f.read(chunk_size)
+          sock.write(sprintf("%x\r\n", s.length) << s << "\r\n")
+        end
+        sock.write "0\r\n\r\n"
+      else
+        while s = f.read(chunk_size)
+          sock.write s
+        end
+      end
+    end
+    
+    def chunk_size
+      1048576 # 1 megabyte
+    end
+  end
+  
+  # Net::HTTP before 1.8.4 doesn't have the use_ssl? method or the Delete request type
+  class HTTP
+    def use_ssl?
+      @use_ssl
+    end unless public_method_defined? :use_ssl?
+    
+    class Delete < HTTPRequest
+      METHOD = 'DELETE'
+      REQUEST_HAS_BODY = false
+      RESPONSE_HAS_BODY = true
+    end unless const_defined? :Delete
+  end
+end
+
+class XmlGenerator < String #:nodoc:
+  attr_reader :xml
+  def initialize
+    @xml = Builder::XmlMarkup.new(:indent => 2, :target => self)
+    super()
+    build
+  end
+end
+#:startdoc: