s33r 0.4.2 → 0.5

data/lib/s33r/s3_logging.rb

@@ -0,0 +1,117 @@
+require 'rubygems'
+require_gem 'builder'
+require File.join(File.dirname(__FILE__), 'libxml_loader')
+require File.join(File.dirname(__FILE__), 's3_acl')
+
+module S33r
+  module S3Logging
+    
+    # For manipulating logging directives on resources
+    # (see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/LoggingHowTo.html).
+    # 
+    # Creating a LoggingResource instance using new and no arguments will generate a "blank" instance;
+    # this can be put to the ?logging URL for a resource to remove logging from it.
+    # 
+    # To set a Bucket up for logging, create a LoggingResource with the correct log_target and 
+    # log_prefix settings and put that to the ?logging URL for a bucket.
+    class LoggingResource
+      attr_reader :log_target, :log_prefix
+    
+      # +log_target+ is the bucket to put logs into.
+      # +log_prefix+ is the prefix for log files put into the +log_target+ bucket.
+      def initialize(log_target=nil, log_prefix=nil)
+        @log_target = log_target
+        @log_prefix = log_prefix
+      end
+      
+      # Generate a BucketLoggingStatus XML document for putting to the ?logging
+      # URL for a resource.
+      def to_xml
+        xml_str = ""
+        xml = Builder::XmlMarkup.new(:target => xml_str, :indent => 0)
+        
+        xml.instruct!
+        
+        # BucketLoggingStatus XML.
+        xml.BucketLoggingStatus({"xmlns" => RESPONSE_NAMESPACE_URI}) {
+          unless @log_target.nil? and @log_prefix.nil?
+            xml.LoggingEnabled {
+              xml.TargetBucket @log_target
+              xml.TargetPrefix @log_prefix
+            }
+          end
+        }
+        
+        xml_str
+      end
+      
+      # Convert XML from S3 response into a LoggingResource
+      # 
+      #-- TODO: tests
+      def self.from_xml(logging_xml)
+        return nil if logging_xml.nil?
+        
+        logging_xml = S33r.remove_namespace(logging_xml)
+        doc = XML.get_xml_doc(logging_xml)
+        
+        log_target = doc.xget('//TargetBucket')
+        log_prefix = doc.xget('//TargetPrefix')
+        
+        self.new(log_target, log_prefix)
+      end
+      
+    end
+  end
+  
+  # Extensions to the S3ACL module to cover logging.
+  module S3ACL
+    class Policy
+    # 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
+      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
+      end
+    end
+    
+    class Grant
+      # 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
+    end
+  end
+end

data/lib/s33r/s3_obj.rb

@@ -1,64 +1,105 @@
 require 'date'
+require File.join(File.dirname(__FILE__), 's3_acl')
+require File.join(File.dirname(__FILE__), 'client')
 
 # Representation of an object stored in a bucket.
 module S33r
-  class S3Object
-    attr_accessor :key, :last_modified, :etag, :size, :owner, :storage_class, :value, :named_bucket, 
-    :content_type, :mime_type
+  class S3Object < Client
+    attr_accessor :key, :last_modified, :etag, :size, :owner, :storage_class, :value,
+    :content_type, :render_as_attachment
     
-    # Metadata set by x-amz-meta- style headers. Note that the bit after x-amz-meta- 
+    # Name of bucket this object is attached to.
+    attr_reader :bucket
+    
+    # Metadata to set with x-amz-meta- style headers. Note that the bit after x-amz-meta- 
     # is stored for each key, rather than the full key.
-    attr_accessor :meta
+    attr_accessor :amz_meta
+    alias :meta :amz_meta
 
-    def initialize(key, metadata={}, amz_meta={}, value=nil)
+    # +options+ can include:
+    # * <tt>:bucket => Bucket</tt>: Bucket this object is attached to.
+    # * <tt>:metadata => Hash</tt>: metadata to use in building the object.
+    # * <tt>:amz_meta => Hash</tt>: metadata specific to Amazon.
+    def initialize(key, value=nil, options={})
       @key = key
-      @meta = amz_meta
+      
       @value = value
+      @content_type = 'text/plain'
+      @render_as_attachment = false
+      @amz_meta = options[:amz_meta] || {}
+      
+      set_bucket(options[:bucket])
+      
+      metadata = options[:metadata] || {}
       set_properties(metadata) unless metadata.empty?
     end
     
+    # Set a bucket instance as the default bucket for this object.
+    def set_bucket(bucket_instance)
+      if bucket_instance
+        @bucket = bucket_instance
+        set_options(@bucket.settings)
+        extend(InBucket)
+      end
+    end
+    alias :bucket= :set_bucket
+    
     # Set the properties of the object from some metadata name-value pairs.
     # 
     # +metadata+ is a hash of properties and their values, used to set the 
     # corresponding properties on the object.
-    # 
-    # +value+ is the data associated with the object on S3.
     def set_properties(metadata)
       # required properties
       @etag = metadata[:etag].gsub("\"", "") if metadata[:etag]
       @last_modified = DateTime.parse(metadata[:last_modified]) if metadata[:last_modified]
       @size = metadata[:size].to_i if metadata[:size]
+      @render_as_attachment = metadata[:render_as_attachment] || false
 
       # only set if creating object from XML (not available otherwise)
-      @owner = metadata[:owner]
+      @owner ||= metadata[:owner]
       
       # only set if creating object from HTTP response
-      @content_type = metadata[:content_type]
+      @content_type = metadata[:content_type] if metadata[:content_type]
     end
     
     # To create an object which reads the content in from a file;
-    # this is not very efficient - it's actually better to use NamedBucket.put_file,
-    # as this will stream out of a file to S3, rather than load the file in
-    # memory first.
-    def self.from_file(key, filename)
+    # you can then save the object to its associated bucket (if you like).
+    def self.from_file(filename, options={})
       mime_type = guess_mime_type(filename)
       content_type = mime_type.simplified
       value = File.open(filename).read
-      self.new(key, { :content_type => content_type }, {}, value)
+      key = options[:key] || filename
+      
+      options.merge!(:metadata => {:content_type => content_type})
+      self.new(key, value, options)
+    end
+    
+    # Create a new instance from a string.
+    def self.from_text(key, text, options={})
+      content_type = 'text/plain'
+      
+      options.merge!(:metadata => {:content_type => content_type})
+      self.new(key, text, options)
     end
 
     # Set properties of the object from an XML string.
     # 
     # +xml_str+ should be a string representing a full XML document,
     # containing a <Contents> element as its root element.
-    def self.from_xml_string(xml_str)
+    def self.from_xml_string(xml_str, options={})
       self.from_xml_node(XML.get_xml_doc(xml_str))
     end
     
-    # Create a new instance from an XML document.
-    def self.from_xml_node(doc)
+    # Create a new instance from an XML document; 
+    # N.B. this instance will have no value associated with it (yet). 
+    # Call the load method to populate it.
+    # 
+    # +options+ is passed to the constructor.
+    def self.from_xml_node(doc, options={})
       metadata = self.parse_xml_node(doc)
-      self.new(metadata[:key], metadata)
+      
+      options.merge!(:metadata => metadata)
+      self.new(metadata[:key], nil, options)
     end
 
     # Get properties of the object from an XML document, e.g. as returned in a bucket listing.
@@ -66,7 +107,6 @@ module S33r
     # +doc+: XML::Document instance to parse to get properties for this object.
     # 
     # Returns the metadata relating to the object, as stored on S3.
-    #-- TODO: include amz-meta elements
     def self.parse_xml_node(doc)
       metadata = {}
       metadata[:key] = doc.xget('Key')
@@ -88,18 +128,20 @@ module S33r
     # do a HEAD for that.
     # 
     # +key+ is the key for the resource (not part of the response).
+    # +resp+ is a Net::HTTPResponse instance to parse.
+    # +options+ is passed through to the constructor (see initialize).
     # 
     # Note that if the resp returns nil, a blank object is created.
-    def self.from_response(key, resp)
+    def self.from_response(key, resp, options={})
       result = self.parse_response(resp)
       if result
         metadata, amz_meta, value = result
+        options.merge!(:metadata => metadata, :amz_meta => amz_meta)
       else
-        metadata = {}
-        amz_meta = {}
         value = nil
       end
-      self.new(key, metadata, amz_meta, value)
+      
+      self.new(key, value, options)
     end
     
     # Parse the response returned by GET on a resource key
@@ -120,67 +162,80 @@ module S33r
         metadata[:size] = resp_headers['content-length'][0]
         metadata[:content_type] = resp_headers['content-type'][0]
         
+        content_disposition = resp_headers['content-disposition']
+        if content_disposition
+          content_disposition = content_disposition[0]
+          if /^attachment/ =~ content_disposition
+            metadata[:render_as_attachment] = true
+          end
+        end
+        
         # x-amz-meta- response headers.
         interesting_header = Regexp.new(METADATA_PREFIX)
-        amz_meta = {}
+        new_amz_meta = {}
         resp.each_header do |key, value|
-          amz_meta[key.gsub(interesting_header, '')] = value if interesting_header =~ key
+          new_amz_meta[key.gsub(interesting_header, '')] = value if interesting_header =~ key
         end
       
         # The actual content of the S3 object.
         value = resp.body
       
-        [metadata, amz_meta, value]
+        [metadata, new_amz_meta, value]
       else
         nil
       end
     end
     
-    # Load content into this object from S3; will perform 
-    # an HTTP request to "refresh" the object (providing the object 
-    # has an association with a bucket it can use for piggybacking).
-    # 
-    # Returns false if value cannot be retrieved.
-    def load
-      if @named_bucket and @named_bucket.key_exists?(@key)
-        resp = @named_bucket.get_raw(@key)
-        if resp.ok?
-          @value = resp.body
-          @content_type = resp.to_hash['content-type']
-          return true
-        else
-          return false
-        end
-      else
-        return false
-      end
+    # Set metadata on the object.
+    def []=(key, value)
+      amz_meta[key] = value
     end
     
-    # Remove this object from its associated NamedBucket.
-    #
-    # Returns false if this object is not associated with a bucket;
-    # otherwise returns the response from S3.
-    def delete
-      if @named_bucket.nil?
-        return false
-      else
-        @named_bucket.delete_resource(@key)
-      end
+    # Get metadata on the object.
+    def [](key)
+      amz_meta[key]
+    end
+  end
+  
+  module InBucket
+    # Send requests using the bucket's options.
+    def request_defaults
+      bucket.request_defaults.merge(:key => key)
+    end
+  
+    # Fetch an object's metadata and content from S3.
+    def fetch(options={})
+      resp = do_get(options)
+      
+      metadata, amz_meta, data = S3Object.parse_response(resp)
+      @amz_meta = amz_meta
+      @value = data
+      set_properties(metadata)
+      true  
     end
     
-    # Save this object back into its bucket.
-    # 
-    # Only works if the object has an associated NamedBucket;
-    # returns false if it doesn't.
-    def save
-      if @named_bucket.nil?
-        return false
-      else
-        headers = {}
-        headers["Content-Type"] = @content_type || ''
-        headers = metadata_headers(headers, meta)
-        @named_bucket.put_stream(@value, @key, headers)
-      end
+    # Save an object to S3.
+    def save(options={})
+      bucket.put(self, options)
     end
+    
+    # Delete the object from S3.
+    def delete(options={})
+      bucket.delete(key, options)
+    end
+    
+    # Change the object's name on S3.
+    def rename(new_key, options={})
+      # Delete the object from S3.
+      bucket.delete(key, options)
+      
+      # Set the new key.
+      self.key = new_key
+      options[:key] = new_key
+      
+      save(options)
+    end
+    alias :mv :rename
+
   end
 end

data/lib/s33r/utility.rb

@@ -0,0 +1,447 @@
+require 'base64'
+require 'time'
+require 'yaml'
+require 'erb'
+require 'cgi'
+
+base = File.dirname(__FILE__)
+require File.join(base, 'libxml_loader')
+require File.join(base, 'libxml_extensions')
+
+# Module to handle S3 operations which don't require an internet connection,
+# i.e. data validation and request-building operations;
+# also holds all the constants relating to S3.
+# 
+# Parts of this code are heavily based on Amazon's code. Here's their license:
+#
+#  This software code is made available "AS IS" without warranties of any
+#  kind.  You may copy, display, modify and redistribute the software
+#  code either by itself or as incorporated into your code; provided that
+#  you do not remove any proprietary notices.  Your use of this software
+#  code is at your own risk and you waive any claim against Amazon
+#  Digital Services, Inc. or its affiliates with respect to your use of
+#  this software code. (c) 2006 Amazon Digital Services, Inc. or its
+#  affiliates.
+module S33r
+  HOST = 's3.amazonaws.com'
+  PORT = 443
+  NON_SSL_PORT = 80
+  METADATA_PREFIX = 'x-amz-meta-'
+  # Size of each chunk (in bytes) to be sent per request when putting files (1Mb).
+  DEFAULT_CHUNK_SIZE = 1048576
+  AWS_HEADER_PREFIX = 'x-amz-'
+  AWS_AUTH_HEADER_VALUE = "AWS %s:%s"
+  INTERESTING_HEADERS = ['content-md5', 'content-type', 'date']
+  # Headers which must be included with every request to S3.
+  REQUIRED_HEADERS = ['Content-Type', 'Date']
+  # Canned ACLs made available by S3.
+  CANNED_ACLS = ['private', 'public-read', 'public-read-write', 'authenticated-read']
+  # HTTP methods which S3 will respond to.
+  METHOD_VERBS = ['GET', 'PUT', 'HEAD', 'DELETE']
+  # Maximum number which can be passed in max-keys parameter when GETting bucket list.
+  BUCKET_LIST_MAX_MAX_KEYS = 1000
+  # Default number of seconds an authenticated URL will last for (15 minutes).
+  DEFAULT_EXPIRY_SECS = 60 * 15
+  # Number of years to use for expiry date when :expires is set to :far_flung_future.
+  FAR_FUTURE = 20
+  # The namespace used for response body XML documents.
+  RESPONSE_NAMESPACE_URI = "http://s3.amazonaws.com/doc/2006-03-01/"
+  
+  # Permissions which can be set within a <Grant>
+  # (see http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingPermissions.html).
+  # 
+  # NB I've missed out the WRITE_ACP permission as this is functionally
+  # equivalent to FULL_CONTROL.
+  PERMISSIONS = { 
+    :read => 'READ',  # permission to read
+    :write => 'WRITE',  # permission to write
+    :read_acl => 'READ_ACP',  # permission to read ACL settings
+    :all => 'FULL_CONTROL'  # do anything
+  }
+  
+  # Used for generating ACL XML documents.
+  NAMESPACE = 'xsi'
+  NAMESPACE_URI = 'http://www.w3.org/2001/XMLSchema-instance'
+  GRANTEE_TYPES = {
+    :amazon_customer => 'AmazonCustomerByEmail', 
+    :canonical_user => 'CanonicalUser',
+    :group => 'Group'
+  }
+  S3_GROUP_TYPES = {
+    :all_users => 'global/AllUsers',
+    :authenticated_users => 'global/AuthenticatedUsers',
+    :log_delivery => 's3/LogDelivery'
+  }
+  GROUP_ACL_URI_BASE = 'http://acs.amazonaws.com/groups/'
+  
+  include S3Exception
+  
+  # Load YAML config. file for S33r operations. The config. file looks like this:
+  # 
+  #   :include: test/files/config.yaml
+  # 
+  # The +options+ section of the YAML file is optional, and can be used 
+  # to add application-specific settings for your application.
+  # 
+  # Note that the loader also runs the config. file through ERB, so you can
+  # add dynamic blocks of ERB (Ruby) code into your files.
+  # 
+  # +config_file+ is the path to the configuration file.
+  # 
+  # Returns a <tt>[config, options]</tt>, where +config+ is a hash of standard S33r 
+  # options (:access, :secret), and +options+ is a hash of general application options.
+  # 
+  # The keys for both hashes are converted from strings into symbols.
+  def self.load_config(config_file)
+    config = YAML::load(ERB.new(IO.read(config_file)).result)
+    
+    options = config.delete('options')
+    options = S33r.keys_to_symbols(options)
+    
+    config = S33r.keys_to_symbols(config)
+    
+    [config, options]
+  end
+
+  # Build canonical string for signing;
+  # modified (slightly) from the Amazon sample code.
+  # 
+  # * +method+ is one of the available METHOD_VERBS.
+  # * +path+ is the path part of the URL to generate the canonical string for.
+  # * +headers+ is a hash of headers which are going to be sent with the request.
+  # * +expires+ is the expiry time set in the querystring for authenticated URLs: 
+  #   if supplied, it is used for the +date+ header.
+  def generate_canonical_string(method, path, headers={}, expires=nil)
+    interesting_headers = {}
+    headers.each do |key, value|
+      lk = key.downcase
+      if (INTERESTING_HEADERS.include?(lk) or lk =~ /^#{AWS_HEADER_PREFIX}/o)
+        interesting_headers[lk] = value
+      end
+    end
+
+    # These fields get empty strings if they don't exist.
+    interesting_headers['content-type'] ||= ''
+    interesting_headers['content-md5'] ||= ''
+
+    # If you're using expires for query string auth, then it trumps date.
+    if not expires.nil?
+      interesting_headers['date'] = expires
+    end
+
+    buf = "#{method}\n"
+    interesting_headers.sort { |a, b| a[0] <=> b[0] }.each do |key, value|
+      if key =~ /^#{AWS_HEADER_PREFIX}/o
+        buf << "#{key}:#{value}\n"
+      else
+        buf << "#{value}\n"
+      end
+    end
+
+    # Ignore everything after the question mark...
+    buf << path.gsub(/\?.*$/, '')
+
+    # ...unless there is an acl, logging or torrent parameter
+    if path =~ /[&?]acl($|&|=)/
+      buf << '?acl'
+    elsif path =~ /[&?]torrent($|&|=)/
+      buf << '?torrent'
+    elsif path =~ /[&?]logging($|&|=)/
+      buf << '?logging'
+    end
+
+    buf
+  end
+
+  # Get the value for the AWS authentication header.
+  def generate_auth_header_value(method, path, headers, aws_access_key, aws_secret_access_key)
+    raise MethodNotAllowed, "Method %s not available" % method if !METHOD_VERBS.include?(method)
+
+    # check the headers needed for authentication have been set
+    missing_headers = REQUIRED_HEADERS - headers.keys
+    if !(missing_headers.empty?)
+      raise MissingRequiredHeaders,
+        "Headers required for AWS auth value are missing: " + missing_headers.join(', ')
+    end
+
+    raise KeysIncomplete, "Access key or secret access key nil" \
+    if aws_access_key.nil? or aws_secret_access_key.nil?
+
+    # get the AWS header
+    canonical_string = generate_canonical_string(method, path, headers)
+    signature = generate_signature(aws_secret_access_key, canonical_string)
+    AWS_AUTH_HEADER_VALUE % [aws_access_key, signature]
+  end
+
+  # Encode the given string with the aws_secret_access_key, by taking the
+  # hmac sha1 sum, and then base64 encoding it.
+  def generate_signature(aws_secret_access_key, str)
+    digest = OpenSSL::HMAC::digest(OpenSSL::Digest::Digest.new("SHA1"), aws_secret_access_key, str)
+    Base64.encode64(digest).strip
+  end
+
+  # Build the headers required with every S3 request (Date and Content-Type); 
+  # options hash can contain extra header settings;
+  # +:date+ and +:content_type+ are required headers, and set to 
+  # defaults if not supplied.
+  def default_headers(existing_headers, options={})
+    headers = {}
+    
+    # which default headers required by AWS are missing?
+    missing_headers = REQUIRED_HEADERS - existing_headers.keys
+
+    if missing_headers.include?('Content-Type')
+      headers['Content-Type'] = options[:content_type] || ''
+    end
+
+    if missing_headers.include?('Date')
+      date = options[:date] || Time.now
+      headers['Date'] = date.httpdate
+    end
+
+    headers
+  end
+
+  # Add metadata headers, correctly prefixing them first,
+  # e.g. you might do metadata_headers({'myname' => 'elliot', 'myage' => 36})
+  # to add two headers to the request:
+  # 
+  #   x-amz-meta-myname: elliot
+  #   x-amz-meta-myage: 36
+  #   
+  # Keys shouldn't have spaces; they can also be represented using symbols.
+  # 
+  # Returns metadata headers appended, with both keys and values as strings.
+  def metadata_headers(metadata={})
+    headers = {}
+    unless metadata.empty?
+      metadata.each { |key, value| headers[METADATA_PREFIX + key.to_s] = value.to_s }
+    end
+    headers
+  end
+  
+  # Content transfer headers: set Content-Type, Content-Transfer-Encoding 
+  # and Content-Disposition headers.
+  # 
+  # <tt>content_type</tt>: content type string to send in the header, e.g. 'text/html'.
+  # 
+  # +key+ is the key for the object: used as the filename if the file is downloaded; defaults to 
+  # 'download' if not set. If you use a path (e.g. '/home/you/photos/me.jpg'), just the last part 
+  # ('me.jpg') is used as the name of the download file.
+  # 
+  # <tt>render_as_attachment</tt>: set to true if you want to add a content disposition header 
+  # which enables the object to be downloaded, rather than shown inline, when fetched by a browser.
+  def content_headers(content_type, key='download', render_as_attachment=false)
+    headers = {}
+    
+    headers['Content-Type'] = content_type || 'text/plain'
+    mime_type = MIME::Types[content_type][0]
+    if mime_type
+      headers['Content-Transfer-Encoding'] = 'binary' if mime_type.binary?
+    end
+    if render_as_attachment
+      headers['Content-Disposition'] = "attachment; filename=#{File.basename(key)}"
+    end
+
+    headers
+  end
+
+  # Get a canned ACL setter header.
+  def canned_acl_header(canned_acl)
+    headers = {}
+    unless canned_acl.nil?
+      unless CANNED_ACLS.include?(canned_acl)
+        raise S3Exception::UnsupportedCannedACL, "The canned ACL #{canned_acl} is not supported"
+      end
+      headers[AWS_HEADER_PREFIX + 'acl'] = canned_acl
+    end
+    headers
+  end
+
+  # Guess a file's mime type.
+  # If the mime_type for a file cannot be guessed, "text/plain" is used.
+  def guess_mime_type(file_name)
+    mime_type = MIME::Types.type_for(file_name)[0]
+    mime_type ||= MIME::Types['text/plain'][0]
+    mime_type
+  end
+
+  # Ensure that a bucket_name is well-formed (no leading or trailing slash).
+  def bucket_name_valid?(bucket_name)
+    if ('/' == bucket_name[0,1] || '/' == bucket_name[-1,1])
+      raise S3Exception::MalformedBucketName, "Bucket name cannot have a leading or trailing slash"
+    end
+  end
+
+  # Convert a hash of name/value pairs to querystring variables.
+  # Name for a variable can be a string or symbol.
+  def generate_querystring(pairs=nil)
+    str = ''
+    pairs ||= {}
+    if pairs.size > 0
+      name_value_pairs = pairs.map do |key, value|
+        if value.nil?
+          key
+        else
+          "#{key}=#{CGI::escape(value.to_s)}"
+        end
+      end
+      str += name_value_pairs.join('&')
+    end
+    str
+  end
+  
+  # Returns the path for this bucket and key.
+  #
+  # +options+:
+  # * <tt>:bucket => 'my-bucket'</tt>: get a path which includes the bucket (unless 
+  #   :subdomain => true is also passed in)
+  # * <tt>:key => 'my-key'</tt>: get a path including a key
+  # * <tt>:querystring => {'acl' => nil, 'page' => 2, ...}</tt>: adds a querystring to path 
+  #   (when generating a signature for a URL, any '?acl' or '?logging' parameters must be 
+  #   included as part of the path before hashing)
+  # * <tt>:subdomain => true</tt>: don't include the bucket name in the path.
+  # * <tt>:acl => true</tt>: append ?acl to the front of the querystring.
+  # * <tt>:logging => true</tt>: append ?logging to the start of the querystring.
+  def s3_path(options={})
+    bucket = options[:bucket]
+    key = options[:key]
+    
+    qstring_pairs = options[:querystring] || {}
+    if options[:acl]
+      qstring_pairs = {:acl => nil}.merge(qstring_pairs)
+    elsif options[:logging]
+      qstring_pairs = {:logging => nil}.merge(qstring_pairs)
+    end
+    
+    qstring = generate_querystring(qstring_pairs)
+  
+    path = '/'
+    path += (bucket + '/') if bucket and !options[:subdomain]
+    path += key if key
+    path += '?' + qstring unless '' == qstring
+    path
+  end
+  
+  # Build a URL for a bucket or object on S3.
+  # 
+  # +options+ are passed through to either s3_authenticated_url or s3_public_url 
+  # (if :authenticated, :access and :secret options are passed, s3_authenticated_url is used):
+  # * <tt>:bucket => 'my-bucket'</tt>: bucket the URL is for.
+  # * <tt>:key => 'my-key'</tt>: the key to produce a URL for.
+  # * <tt>:use_ssl => true</tt>: return an https:// URL.
+  # * <tt>:subdomain => true</tt>: use :bucket as the subdomain 
+  #   to produce a bucket URL like 'elliot.s3.amazonaws.com' instead of 
+  #   's3.amazonaws.com/elliot'.  Note that this 
+  #   is NOT SUPPORTED for authenticated requests or SSL requests.
+  # * <tt>:path => '/bucket/key'</tt>: include given path on end of URL; if not set, 
+  #   a path is generated from any bucket and/or key given
+  # * <tt>:access => 'aws access key'</tt>: Generate authenticated URL.
+  # * <tt>:secret => 'aws secret access key'</tt>: Generate authenticated URL.
+  # * <tt>:authenticated => true</tt>: Produce an authenticated URL.
+  # * <tt>:querystring => {'name' => 'value', 'test' => nil, ...}</tt>: add querystring 
+  #   parameters to the URL; NB any keys with a nil value are added to the querystring 
+  #   as keys without values. Note that querystring parameters are just appended in the order they 
+  #   are returned by the map iterator for a hash.
+  # * <tt>:acl => true</tt>: append ?acl to the front of the querystring.
+  # * <tt>:logging => true</tt>: append ?logging to the start of the querystring.
+  def s3_url(options={})
+    # Turn off the subdomain option if using SSL.
+    options[:subdomain] = false if options[:use_ssl]
+    
+    access = options[:access]
+    secret = options[:secret]
+    if access and secret and options[:authenticated]
+      # Turn off the subdomain option (it doesn't work with authenticated URLs).
+      options[:subdomain] = false
+      s3_authenticated_url(access, secret, options)
+    else
+      s3_public_url(options)
+    end
+  end
+  
+  # Public readable URL for a bucket and resource.
+  # 
+  # +options+ are passed through from s3_url; only :access and :secret are irrelevant of the options 
+  # available to s3_url.
+  # 
+  # Note that if a :path option is not set, a path is generated from any :bucket and/or :path 
+  # parameters supplied.
+  def s3_public_url(options)
+    scheme = options[:use_ssl] ? 'https' : 'http'
+    path = options[:path]
+    path ||= s3_path(options)
+    host = HOST
+    host = (options[:bucket] + "." + host ) if options[:subdomain]
+    "#{scheme}://" + host + path
+  end
+  
+  # Generate a get-able URL for an S3 resource key which passes authentication in querystring. Note 
+  # that this will correctly generate authenticated URLs for logging and ACL resources.
+  # 
+  # +options+ are passed through to s3_path and s3_url; an :expires option is also available:
+  # * <tt>:expires => <date time></tt>: when the URL expires (seconds since the epoch); S33r.parse_expiry 
+  #   is used to generate a suitable value from a date/time string, or you can use an int. Use :far_flung_future 
+  #   to get some time in the distant future. Defaults to current time + S33r::DEFAULT_EXPIRY_SECS.
+  def s3_authenticated_url(aws_access_key, aws_secret_access_key, options={})
+    raise KeysIncomplete, "You must supply both an AWS access key and secret access key to create \
+    an authenticated URL" if aws_access_key.nil? or aws_secret_access_key.nil?
+  
+    path = s3_path(options)
+    expires = S33r.parse_expiry(options[:expires])
+    
+    canonical_string = generate_canonical_string('GET', path, {}, expires)
+    signature = generate_signature(aws_secret_access_key, canonical_string)
+    
+    querystring = generate_querystring({'Signature' => signature, 'Expires' => expires,
+    'AWSAccessKeyId' => aws_access_key })
+    
+    options[:path] = path
+    base_url = s3_public_url(options)
+    /\?/ =~ base_url ? base_url += '&' : base_url += '?'
+    base_url += querystring
+    base_url
+  end
+  
+  # Return the hash +hsh+ with keys converted to symbols.
+  def self.keys_to_symbols(hsh)
+    symbolised = {}
+    hsh.each_pair do |key, value|
+      symbolised[key.to_sym] = value
+    end
+    symbolised
+  end
+  
+  # Parse an expiry date into seconds since the epoch.
+  # 
+  # +expires+ can be set to :far_flung_future to get a time FAR_FUTURE years in the future;
+  # or to a specific date (parseable by ParseDate); or to an integer
+  # representing seconds since the epoch. If you leave it blank, you'll get 
+  # the current time + DEFAULT_EXPIRY_SECS.
+  # 
+  # Returns an integer representing seconds since the epoch.
+  def self.parse_expiry(expires=nil)
+    unless expires.kind_of?(Integer)
+      if expires.is_a?(String)
+        expires = Time.parse(expires).to_i
+      else
+        base_expires = Time.now.to_i
+        if :far_flung_future == expires
+          # 50 years (same as forever in computer terms)
+          expires = (base_expires + (60 * 60 * 24 * 365.25 * FAR_FUTURE)).to_i
+        else
+          # default to DEFAULT_EXPIRY_SECS seconds from now if expires not set
+          expires = base_expires + DEFAULT_EXPIRY_SECS
+        end
+      end
+    end
+    expires
+  end
+  
+  # Remove the namespace declaration from S3 XML response bodies (libxml
+  # isn't fond of it).
+  def self.remove_namespace(xml_in)
+    namespace = S33r::RESPONSE_NAMESPACE_URI.gsub('/', '\/')
+    xml_in.gsub(/ xmlns="#{namespace}"/, '')
+  end
+end