s33r 0.4.2 → 0.5

data/lib/s33r/networking.rb

@@ -0,0 +1,197 @@
+require 'uri'
+require 'openssl'
+require 'net/http'
+require 'net/https'
+require 'stringio'
+
+base = File.dirname(__FILE__)
+require File.join(base, 's33r_exception')
+require File.join(base, 's33r_http')
+require File.join(base, 'utility')
+
+# Core functionality for managing HTTP requests to S3.
+module S33r
+  module Networking
+    include S3Exception
+    include Net
+    
+    #-- These are specific to the mechanics of the HTTP request.
+    
+    # Net::HTTP instance.
+    attr_accessor :client
+    
+    # Are HTTP connections persistent?
+    attr_accessor :persistent
+    
+    # Default chunk size for connections.
+    attr_accessor :chunk_size
+    
+    # Should requests be dumped?
+    attr_accessor :dump_requests
+    
+    # The last response received by the client.
+    attr_reader :last_response
+    
+    # Get default options to use on every response.
+    def request_defaults
+      @request_defaults || {}
+    end
+    
+    # Set the defaults.
+    def request_defaults=(options={})
+      @request_defaults = options
+    end
+  
+    # Send a request over the wire.
+    # 
+    # This method streams +data+ if it responds to the +stat+ method
+    # (as file handles do).
+    # 
+    # Keys for +headers+ should be strings (e.g. 'Content-Type').
+    # 
+    # +url_options+ is a standard set of options acceptable to s3_url; 
+    # if any options aren't set, they are set using the +request_defaults+ method 
+    # (options passed in here override defaults).
+    # 
+    # You can also pass <tt>:authenticated => false</tt> if you want to visit a 
+    # public URL here; otherwise, an Authorization header is generated and sent. If the client 
+    # doesn't have an access key or secret access key specified, however, trying to create 
+    # an access key will result in an error being raised.
+    # 
+    # Returns a Net::HTTPResponse instance.
+    def do_request(method, url_options={}, data=nil, headers={})
+      # Use the default settings only if not specified in url_options.
+      url_options = request_defaults.merge(url_options)
+      
+      # Get the URL.
+      url = s3_url(url_options)
+      uri = URI(url)
+      
+      # Bar any except the allowed methods.
+      raise MethodNotAllowed, "The #{method} HTTP method is not supported" unless METHOD_VERBS.include?(method)
+      
+      # Get a requester.
+      path = uri.path
+      path += "?" + uri.query if uri.query
+      req = eval("HTTP::" + method[0,1].upcase + method[1..-1].downcase + ".new('#{path}')")
+      
+      req.chunk_size = chunk_size || DEFAULT_CHUNK_SIZE
+
+      # Add the S3 headers which are always required.
+      headers.merge!(default_headers(headers))
+
+      # Headers for canned ACL
+      headers.merge! canned_acl_header(url_options[:canned_acl]) if 'PUT' == method
+
+      # Generate the S3 authorization header if the client has 
+      # the appropriate instance variable getters.
+      unless (false == url_options[:authenticated])
+        headers['Authorization'] = generate_auth_header_value(method, path, headers,
+        url_options[:access], url_options[:secret])
+      end
+
+      # Insert the headers into the request object.
+      headers.each do |key, value|
+        req[key] = value
+      end
+
+      # Add data to the request as a stream.
+      if req.request_body_permitted?
+        # For streaming files; NB Content-Length will be set by Net::HTTP
+        # for character-based data: this section of is only used
+        # when reading directly from a file.
+        if data.respond_to?(:stat)
+          length = data.stat.size
+        # Strings can be streamed too.
+        elsif data.is_a?(String)
+          length = data.length
+          data = StringIO.new(data)
+        else
+          length = 0
+        end
+        
+        # Data can be streamed if it responds to the read method.
+        if data.respond_to?(:read)
+          req.body_stream = data
+          req['Content-Length'] = length.to_s
+          data = nil
+        end
+      else
+        data = nil
+      end
+      
+      puts req.to_s if @dump_requests
+      
+      # Set up the request.
+      ### <snip> start shameless stealing from Marcel Molina
+      request_runner = Proc.new do
+        response = @client.request(req, data)
+        
+        # Add some nice messages to the response (like the S3 error 
+        # message if it occurred).
+        response.conveniencify(method)
+        @last_response = response
+        
+        return response
+      end
+
+      # Get a client instance.
+      init_client(uri)
+
+      # Run the request.
+      if persistent
+        @client.start unless @client.started?
+        response = request_runner.call
+      else
+        response = @client.start(&request_runner)
+      end
+
+      response
+      ### </snip> end shameless stealing from Marcel Molina
+    end
+    
+    # Setup an HTTP client instance.
+    # 
+    # Note that when you send your first request, the client is set 
+    # up using whichever parameters for host and port you passed the first 
+    # time. If you change the host or port, the client will be regenerated.
+    # 
+    # +url+ is a URI instance generated from a full URL, including a host 
+    # name and scheme.
+    def init_client(url)
+      host = url.host || HOST
+      port = url.port
+      if @client.nil? or @client.port != port or @client.address != host
+        @client = HTTP.new(host, port)
+        @client.use_ssl = false
+        
+        # Check whether client needs to use SSL.
+        if port == PORT
+          # turn off SSL certificate verification
+          @client.verify_mode = OpenSSL::SSL::VERIFY_NONE
+          @client.use_ssl = true
+        end
+      end
+    end
+    
+    # Perform a get request.
+    def do_get(options={}, headers={})
+      do_request('GET', options, nil, headers)
+    end
+    
+    # Perform a put request.
+    def do_put(data, options={}, headers={})
+      do_request('PUT', options, data, headers)
+    end
+    
+    # Perform a delete request.
+    def do_delete(options={}, headers={})
+      do_request('DELETE', options, headers)
+    end
+    
+    # Perform a head request.
+    def do_head(options={}, headers={})
+      do_request('HEAD', options, headers)
+    end
+  end
+end

data/lib/s33r/s33r_exception.rb

@@ -1,25 +1,38 @@
 module S33r
-  module S33rException
-
-    class MethodNotAvailable < Exception
+  module S3Exception
+  
+    # For errors originated by S3
+    class S3OriginatedException < Exception
+      attr_reader :s3_code, :s3_message
+      
+      def initialize(code=nil, message=nil)
+        @s3_code = code
+        @s3_message = message
+      end
+      
+      def to_s
+        "S3 returned an error\nError code: #{@s3_code}; error message: #{@s3_message}"
+      end
+    end
+    
+    def self.error(s3_code, s3_message=nil)
+      S3OriginatedException.new(s3_code, s3_message)
     end
 
+    # Errors originated by S33r.
+    class MethodNotAllowed < Exception
+    end
+    
     class MissingRequiredHeaders < Exception
     end
 
     class UnsupportedCannedACL < Exception
     end
 
-    class UnsupportedHTTPMethod < Exception
-    end
-
     class MalformedBucketName < Exception
     end
     
-    class MissingBucketName < Exception
-    end
-
-    class MissingResource < Exception
+    class InvalidBucket < Exception
     end
 
     class BucketListingMaxKeysError < Exception
@@ -28,23 +41,21 @@ module S33r
     class InvalidBucketListing < Exception
     end
     
-    class S3FallenOver < Exception
+    class InvalidGroupType < Exception
     end
     
-    class InvalidS3GroupType < Exception
+    class InvalidPermission < Exception
     end
     
-    class InvalidPermission < Exception
+    # Raised if an attempt is made to generate an authenticated URL 
+    # with one of the required AWS keys missing.
+    class KeysIncomplete < Exception
     end
     
     # Raised if a bucket cannot be used as a log target
-    # (i.e. if LogDelivery permissions not set - see S33r::S3ACL::ACLDoc.add_log_target_grants)
+    # (i.e. if LogDelivery permissions not set - see S33r::S3ACL::Policy.add_log_target_grants)
     class BucketNotLogTargetable < Exception
     end
-    
-    # Raised if you try to do a put with empty body
-    class TryingToPutEmptyResource < Exception
-    end
 
   end
 end

data/lib/s33r/s33r_http.rb

@@ -1,31 +1,48 @@
 require 'net/http'
-require File.join(File.dirname(__FILE__), 's33r_exception')
+base = File.dirname(__FILE__)
+require File.join(base, 's33r_exception')
+require File.join(base, 'utility')
+require File.join(base, 'libxml_loader')
+require File.join(base, 'libxml_extensions')
 
-# Addtions to the Net::HTTP classes
-#
-# Adds some convenience functions for checking response status.
+# Additions to the Net::HTTP classes
+
+# Adds some convenience functions for checking response status, parsing 
+# error messages from 
 class Net::HTTPResponse
-  attr_accessor :success
   attr_writer :body
   
-  def check_s3_availability
-    if (500..503).include? code.to_i
-      raise S33r::S33rException::S3FallenOver, "S3 has fallen over! (got a #{code} code in response)"
+  # An exception wrapped around the response from S3
+  attr_reader :s3_error
+  
+  # Wrap responses properly so the S3 error codes don't have to be read.
+  def conveniencify(method)
+    if '200' == code
+      @ok = true
+      @s3_message = 'Request successful'
+    # 204 returned for successful bucket or item deletes
+    elsif '204' == code and 'DELETE' == method
+      @s3_message = 'Successfully deleted'
+      @ok = true
+    else
+      @ok = false
+      if body.nil?
+        @s3_error = S33r::S3Exception.error(code)
+      else
+        # Get the S3 error message and code
+        error_response = XML.get_xml_doc(body)
+        s3_code = error_response.xget('//Code')
+        s3_message = error_response.xget('//Message')
+        
+        @s3_error = S33r::S3Exception.error(s3_code, s3_message)
+      end
     end
   end
 
   def ok?
-    success
-  end
-
-  def success
-    code == '200'
-  end
-
-  def not_found
-    code = '404'
+    @ok || false
   end
-
+  
   def to_s
     body
   end
@@ -52,6 +69,7 @@ class Net::HTTPGenericRequest
     self.each_capitalized do |key, value|
       str += "#{key}: #{value}\n"
     end
+    str += "*******\n" + body + "\n" unless body.nil?
     str += "*******\n\n"
     str
   end

data/lib/s33r/s3_acl.rb

@@ -15,9 +15,9 @@ module S33r
     # 
     # Represents both retrieved ACL XML or can be built up 
     # using objects and converted to XML.
-    # NB the ACLDoc is oblivious to the resource it is going 
+    # NB the Policy is oblivious to the resource it is going 
     # to be applied to.
-    class ACLDoc
+    class Policy
       # List of grants to be applied.
       attr_accessor :grants, :owner
       
@@ -27,7 +27,7 @@ module S33r
         @owner = owner
       end
       
-      # Create an ACLDoc instance from a raw Access Control Policy XML document.
+      # Create an Policy instance from a raw Access Control Policy XML document.
       # 
       # +acl_xml+ is a raw Access Control Policy XML string (NOT libxml Document or Node).
       # 
@@ -50,7 +50,7 @@ module S33r
           grants << Grant.new(grantee, permission)
         end
         
-        ACLDoc.new(owner, grants)
+        Policy.new(owner, grants)
       end
       
       # Generate AccessControlPolicy XML document.
@@ -81,12 +81,10 @@ module S33r
       # Returns true if grant was added;
       # false otherwise (grant already exists).
       def add_grant(grant)
-        if @grants.include?(grant)
-          return false
-        else
+        unless @grants.include?(grant)
           @grants << grant
-          return true
         end
+        self
       end
       
       # Remove a grant from the ACL document. Note that if you
@@ -100,6 +98,7 @@ module S33r
       # false if it wasn't in the document.
       def remove_grant(grant)
         @grants.delete_if { |g| grant == g }
+        self
       end
       
       # Does the ACL contain a grant for public reads?
@@ -117,42 +116,15 @@ module S33r
         add_grant(Grant.public_read_grant)
       end
       
-      # Does the ACL make the associated resource available as a log target?
-      def log_targetable?
-        log_target_grants = Grant.log_target_grants
-        log_target_grants.each { |g| return false if !grants.include?(g) }
-        return true
-      end
-      
-      # Add permissions to an instances which give READ_ACL
-      # and WRITE permissions to the LogDelivery group. Used
-      # to enable a bucket as a logging destination.
-      # 
-      # Returns true if grants added, false otherwise
-      # (if already a log target).
-      def add_log_target_grants
-        if log_targetable?
-          return false
-        else
-          Grant.log_target_grants.each { |g| add_grant(g) }
-          return true
-        end
+      # Remove the public READ permission from this instance.
+      def remove_public_read_grant
+        remove_grant(Grant.public_read_grant)
       end
       
-      # Remove log target ACLs from the document.
-      # 
-      # Returns true if all log target grants were removed;
-      # false otherwise.
-      # 
-      # NB even if this method returns false, that doesn't mean
-      # the bucket is still a log target. Use log_targetable? to check
-      # whether a bucket can be used as a log target.
-      def remove_log_target_grants
-        ok = true
-        Grant.log_target_grants.each { |g| ok = ok and remove_grant(g) }
-        ok
+      # String representation of the policy.
+      def to_s
+        @grants.inject('') {|acc, grant| acc += "* " + grant.to_s + "\n"}
       end
-      
     end
   
     # Representation of an S3 Grant 
@@ -171,7 +143,8 @@ module S33r
         else
           @permission = PERMISSIONS[permission]
         end
-        raise InvalidPermission, "Permission #{permission.to_s} is not a valid permission specifier" if @permission.nil?
+        raise S3Exception::InvalidPermission, \
+        "Permission #{permission.to_s} is not a valid permission specifier" if @permission.nil?
       end
       
       # Note that setting a grant for an Amazon customer is the
@@ -196,15 +169,6 @@ module S33r
         Grant.new(Group.new(:all_users), :read)
       end
       
-      # Generator for a grant which gives the LogDelivery group
-      # write and read_acl permissions on a bucket.
-      # 
-      # Returns an array with the two required Grant instances.
-      def Grant.log_target_grants
-        log_delivery_group = Group.new(:log_delivery)
-        [Grant.new(log_delivery_group, :read_acl), Grant.new(log_delivery_group, :write)]
-      end
-      
       # Convert a Grant object into an XML fragment.
       def to_xml
         xml_str = ""
@@ -239,6 +203,10 @@ module S33r
         return true
       end
       
+      def to_s
+        "#{@grantee.to_s} has permission #{@permission}"
+      end
+      
     end
 
     # Abstract representation of an S3 Grantee.
@@ -291,6 +259,10 @@ module S33r
         @grantee_type = GRANTEE_TYPES[:amazon_customer]
         @email_address = email_address
       end
+      
+      def to_s
+        "Amazon customer with address '#{@email_address}"
+      end
     end
     
     # An S3 user.
@@ -315,6 +287,10 @@ module S33r
         display_name = user_xml_doc.xget('DisplayName')
         new(user_id, display_name)
       end
+      
+      def to_s
+        "Canonical user '#{@display_name}' (with user ID '#{@user_id}')"
+      end
     end
     
     # One of the predefined S3 groups.
@@ -327,11 +303,15 @@ module S33r
       # one of the pre-defined Amazon group types.
       def initialize(group_type)
         unless S3_GROUP_TYPES.has_key?(group_type)
-          raise InvalidS3GroupType, 'No such group type #{group_type}'
+          raise S3Exception::InvalidGroupType, 'No such group type #{group_type}'
         end
         @group_type = S3_GROUP_TYPES[group_type]
         @grantee_type = GRANTEE_TYPES[:group]
       end
+      
+      def to_s
+        "Group '#{@group_type}'"
+      end
     end
     
   end