aws-s3 0.1.0

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,130 @@
+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
+    
+    # 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 infered 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,186 @@
+#:stopdoc:
+
+class Hash
+  def to_query_string(include_question_mark = true)
+    return '' if empty?
+    query_string = ''
+    query_string << '?' if include_question_mark
+    query_string << inject([]) do |parameters, (key, value)|
+      parameters << [key, value].map {|element| CGI.escape(element.to_s)}.join('=')
+    end.join('&')
+  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
+  def previous!
+    self[-1] = self[-1] - 1
+    self
+  end
+  
+  def previous
+    dup.previous!
+  end
+  
+  def to_header
+    downcase.gsub('_', '-')
+  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.9'
+  
+  def memoize(reload = false, storage = nil)
+    storage = "@#{storage || __method__(1)}"
+    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)
+    require library
+  rescue LoadError => library_not_installed
+    begin
+      require 'rubygems'
+      require library
+    rescue LoadError
+      raise library_not_installed
+    end
+  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)
+        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
+
+module SelectiveAttributeProxy
+  def self.included(klass)
+    klass.extend(ClassMethods)
+    klass.class_eval(<<-EVAL, __FILE__, __LINE__)
+      # Default name for attribute storage
+      @@attribute_proxy         = :attributes
+      @@attribute_proxy_options = {:exclusively => true}
+      
+      def self.attribute_proxy
+        @@attribute_proxy
+      end
+      
+      def self.attribute_proxy_options
+        @@attribute_proxy_options
+      end
+      
+      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
+        class_variable_set(:@@attribute_proxy, attribute_name)
+      end
+      class_variable_set(:@@attribute_proxy_options, options)
+    end
+  end
+end
+
+class String
+  def underscore
+    gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+    gsub(/([a-z\d])([A-Z])/,'\1_\2').
+    downcase
+  end
+end
+
+class XmlGenerator < String #:nodoc:
+  attr_reader :xml
+  def initialize
+    @xml = Builder::XmlMarkup.new(:indent => 2, :target => self)
+    super()
+    build
+  end
+end
+#:startdoc:

data/lib/aws/s3/logging.rb

@@ -0,0 +1,163 @@
+module AWS
+  module S3
+    # A bucket can be set to log the requests made on it. By default logging is turned off. You can check if a bucket has logging enabled:
+    # 
+    #   Bucket.logging_enabled_for? 'jukebox'
+    #   # => false
+    # 
+    # Enabling it is easy:
+    # 
+    #   Bucket.enable_logging_for('jukebox')
+    # 
+    # Unless you specify otherwise, logs will be written to the bucket you want to log. The logs are just like any other object. By default they will start with the prefix 'log-'. You can customize what bucket you want the logs to be delivered to, as well as customize what the log objects' key is prefixed with by setting the <tt>target_bucket</tt> and <tt>target_prefix</tt> option:
+    # 
+    #   Bucket.enable_logging_for(
+    #     'jukebox', 'target_bucket' => 'jukebox-logs'
+    #   )
+    # 
+    # Now instead of logging right into the jukebox bucket, the logs will go into the bucket called jukebox-logs.
+    # 
+    # Once logs have accumulated, you can access them using the <tt>log</tt> method:
+    # 
+    #   pp Bucket.logs('jukebox')
+    #   [#<AWS::S3::S3Object '/jukebox-logs/log-2006-11-14-07-15-24-2061C35880A310A1'>,
+    #    #<AWS::S3::S3Object '/jukebox-logs/log-2006-11-14-08-15-27-D8EEF536EC09E6B3'>,
+    #    #<AWS::S3::S3Object '/jukebox-logs/log-2006-11-14-08-15-29-355812B2B15BD789'>]
+    #
+    # Disabling logging is just as simple as enabling it:
+    #
+    #  Bucket.disable_logging_for('jukebox')
+    module Logging
+      # Logging status captures information about the calling bucket's logging settings. If logging is enabled for the bucket
+      # the status object will indicate what bucket the logs are written to via the <tt>target_bucket</tt> method as well as
+      # the logging key prefix with via <tt>target_prefix</tt>.
+      #
+      # See the documentation for Logging::Management::ClassMethods for more information on how to get the logging status of a bucket. 
+      class Status
+        include SelectiveAttributeProxy #:nodoc:
+        attr_reader :enabled
+        alias_method :logging_enabled?, :enabled
+      
+        def initialize(attributes = {}) #:nodoc:
+          attributes  = {'target_bucket' => nil, 'target_prefix' => nil}.merge(attributes)
+          @enabled    = attributes.has_key?('logging_enabled')
+          @attributes = attributes.delete('logging_enabled') || attributes
+        end
+      
+        def to_xml #:nodoc:
+          Builder.new(self).to_s
+        end
+      
+        private
+          attr_reader :attributes
+        
+          class Builder < XmlGenerator #:nodoc:
+            attr_reader :logging_status
+            def initialize(logging_status)
+              @logging_status = logging_status
+              super()
+            end
+          
+            def build
+              xml.tag!('BucketLoggingStatus', 'xmlns' => 'http://s3.amazonaws.com/doc/2006-03-01/') do
+                if logging_status.target_bucket && logging_status.target_prefix
+                  xml.LoggingEnabled do
+                    xml.TargetBucket logging_status.target_bucket
+                    xml.TargetPrefix logging_status.target_prefix
+                  end
+                end
+              end
+            end
+          end
+        end
+        
+      module Management #:nodoc:
+        def self.included(klass) #:nodoc:
+          klass.extend(ClassMethods)
+          klass.extend(LoggingGrants)
+        end
+        
+        module ClassMethods
+          # Returns the logging status for the bucket named <tt>name</tt>. From the logging status you can determine the bucket logs are delivered to
+          # and what the bucket object's keys are prefixed with. For more information see the Logging::Status class.
+          #
+          #   Bucket.logging_status_for 'marcel'
+          def logging_status_for(name = nil, status = nil)
+            if name.is_a?(Status)
+              status = name
+              name   = nil
+            end
+
+            path = path(name) << '?logging'
+            status ? put(path, {}, status.to_xml) : Status.new(get(path).parsed)
+          end
+          alias_method :logging_status, :logging_status_for
+          
+          # Enables logging for the bucket named <tt>name</tt>. You can specify what bucket to log to with the <tt>'target_bucket'</tt> option as well
+          # as what prefix to add to the log files with the <tt>'target_prefix'</tt> option. Unless you specify otherwise, logs will be delivered to
+          # the same bucket that is being logged and will be prefixed with <tt>log-</tt>.
+          def enable_logging_for(name = nil, options = {})
+            name            = bucket_name(name)
+            default_options = {'target_bucket' => name, 'target_prefix' => 'log-'}
+            options         = default_options.merge(options)
+            grant_logging_access_to_target_bucket(options['target_bucket'])
+            logging_status(name, Status.new(options))
+          end
+          alias_method :enable_logging, :enable_logging_for
+          
+          # Disables logging for the bucket named <tt>name</tt>.
+          def disable_logging_for(name = nil)
+            logging_status(bucket_name(name), Status.new)
+          end
+          alias_method :disable_logging, :disable_logging_for
+          
+          # Returns true if logging has been enabled for the bucket named <tt>name</tt>.
+          def logging_enabled_for?(name = nil)
+            logging_status(bucket_name(name)).logging_enabled?
+          end
+          alias_method :logging_enabled?, :logging_enabled_for?
+          
+          # Returns the collection of logs for the bucket named <tt>name</tt>.
+          #
+          #   Bucket.logs_for 'marcel'
+          def logs_for(name = nil)
+            name = bucket_name(name)
+            logging_status = logging_status_for(name)
+            return [] unless logging_status.logging_enabled?
+            objects(logging_status.target_bucket, :prefix => logging_status.target_prefix)
+          end
+          alias_method :logs, :logs_for
+        end
+        
+        module LoggingGrants #:nodoc:
+          def grant_logging_access_to_target_bucket(target_bucket)
+            acl = acl(target_bucket)
+            acl.grants << ACL::Grant.grant(:logging_write)
+            acl.grants << ACL::Grant.grant(:logging_read_acp)
+            acl(target_bucket, acl)
+          end
+        end
+        
+        def logging_status
+          self.class.logging_status_for(name)
+        end
+        
+        def enable_logging(*args)
+          self.class.enable_logging_for(name, *args)
+        end
+        
+        def disable_logging(*args)
+          self.class.disable_logging_for(name, *args)
+        end
+        
+        def logging_enabled?
+          self.class.logging_enabled_for?(name)
+        end
+        
+        def logs
+          self.class.logs_for(name)
+        end
+      end
+    end
+  end
+end