steamcannon-s3 0.3.2

data/lib/s3/object.rb

@@ -0,0 +1,249 @@
+module S3
+
+  # Class responsible for handling objects stored in S3 buckets
+  class Object
+    include Parser
+    extend Forwardable
+
+    attr_accessor :content_type, :content_disposition, :content_encoding
+    attr_reader :last_modified, :etag, :size, :bucket, :key, :acl, :storage_class
+    attr_writer :content
+
+    def_instance_delegators :bucket, :name, :service, :bucket_request, :vhost?, :host, :path_prefix
+    def_instance_delegators :service, :protocol, :port, :secret_access_key
+    private_class_method :new
+
+    # Compares the object with other object. Returns true if the key
+    # of the objects are the same, and both have the same buckets (see
+    # Bucket equality)
+    def ==(other)
+      other.equal?(self) || (other.instance_of?(self.class) && self.key == other.key && self.bucket == other.bucket)
+    end
+
+    # Returns full key of the object: e.g. <tt>bucket-name/object/key.ext</tt>
+    def full_key
+      [name, key].join("/")
+    end
+
+    # Assigns a new +key+ to the object, raises ArgumentError if given
+    # key is not valid key name
+    def key=(key)
+      raise ArgumentError.new("Invalid key name: #{key}") unless key_valid?(key)
+      @key ||= key
+    end
+
+    # Assigns a new ACL to the object. Please note that ACL is not
+    # retrieved from the server and set to "public-read" by default.
+    #
+    # ==== Example
+    #   object.acl = :public_read
+    def acl=(acl)
+      @acl = acl.to_s.gsub("_", "-") if acl
+    end
+    
+    # Assigns a new storage class (RRS) to the object. Please note 
+    # that the storage class is not retrieved from the server and set
+    # to "STANDARD" by default.
+    #
+    # ==== Example
+    #   object.storage_class = :reduced_redundancy
+    def storage_class=(storage_class)
+      @storage_class = storage_class.to_s.upcase if storage_class
+    end
+
+    # Retrieves the object from the server. Method is used to download
+    # object information only (content type, size and so on). It does
+    # NOT download the content of the object (use the #content method
+    # to do it).
+    def retrieve
+      object_headers
+      self
+    end
+
+    # Retrieves the object from the server, returns true if the object
+    # exists or false otherwise. Uses #retrieve method, but catches
+    # S3::Error::NoSuchKey exception and returns false when it happens
+    def exists?
+      retrieve
+      true
+    rescue Error::NoSuchKey
+      false
+    end
+
+    # Download the content of the object, and caches it. Pass true
+    # to clear the cache and download the object again.
+    def content(reload = false)
+      if reload or @content.nil?
+        get_object
+      end
+      @content
+    end
+
+    # Saves the object, returns true if successfull.
+    def save
+      put_object
+      true
+    end
+
+    # Copies the file to another key and/or bucket.
+    #
+    # ==== Options
+    # * <tt>:key</tt> - New key to store object in
+    # * <tt>:bucket</tt> - New bucket to store object in (instance of
+    #   S3::Bucket)
+    # * <tt>:acl</tt> - ACL of the copied object (default:
+    #   "public-read")
+    # * <tt>:content_type</tt> - Content type of the copied object
+    #   (default: "application/octet-stream")
+    def copy(options = {})
+      copy_object(options)
+    end
+
+    # Destroys the file on the server
+    def destroy
+      delete_object
+      true
+    end
+
+    # Returns Object's URL using protocol specified in service,
+    # e.g. <tt>http://domain.com.s3.amazonaws.com/key/with/path.extension</tt>
+    def url
+      URI.escape("#{protocol}#{host}/#{path_prefix}#{key}")
+    end
+
+    # Returns a temporary url to the object that expires on the
+    # timestamp given. Defaults to one hour expire time.
+    def temporary_url(expires_at = Time.now + 3600)
+      signature = Signature.generate_temporary_url_signature(:bucket => name,
+                                                             :resource => key,
+                                                             :expires_at => expires_at,
+                                                             :secret_access_key => secret_access_key)
+
+      "#{url}?AWSAccessKeyId=#{self.bucket.service.access_key_id}&Expires=#{expires_at.to_i.to_s}&Signature=#{signature}"
+    end
+
+    # Returns Object's CNAME URL (without <tt>s3.amazonaws.com</tt>
+    # suffix) using protocol specified in Service,
+    # e.g. <tt>http://domain.com/key/with/path.extension</tt>. (you
+    # have to set the CNAME in your DNS before using the CNAME URL
+    # schema).
+    def cname_url
+      URI.escape("#{protocol}#{name}/#{key}") if bucket.vhost?
+    end
+
+    def inspect #:nodoc:
+      "#<#{self.class}:/#{name}/#{key}>"
+    end
+
+    private
+
+    attr_writer :last_modified, :etag, :size, :original_key, :bucket
+
+    def copy_object(options = {})
+      key = options[:key] or raise ArgumentError, "No key given"
+      raise ArgumentError.new("Invalid key name: #{key}") unless key_valid?(key)
+      bucket = options[:bucket] || self.bucket
+
+      headers = {}
+
+      headers[:x_amz_acl] = options[:acl] || acl || "public-read"
+      headers[:content_type] = options[:content_type] || content_type || "application/octet-stream"
+      headers[:content_encoding] = options[:content_encoding] if options[:content_encoding]
+      headers[:content_disposition] = options[:content_disposition] if options[:content_disposition]
+      headers[:x_amz_copy_source] = full_key
+      headers[:x_amz_metadata_directive] = "REPLACE"
+      headers[:x_amz_copy_source_if_match] = options[:if_match] if options[:if_match]
+      headers[:x_amz_copy_source_if_none_match] = options[:if_none_match] if options[:if_none_match]
+      headers[:x_amz_copy_source_if_unmodified_since] = options[:if_modified_since] if options[:if_modified_since]
+      headers[:x_amz_copy_source_if_modified_since] = options[:if_unmodified_since] if options[:if_unmodified_since]
+
+      response = bucket.send(:bucket_request, :put, :path => key, :headers => headers)
+      object_attributes = parse_copy_object_result(response.body)
+
+      object = Object.send(:new, bucket, object_attributes.merge(:key => key, :size => size))
+      object.acl = response["x-amz-acl"]
+      object.content_type = response["content-type"]
+      object.content_encoding = response["content-encoding"]
+      object.content_disposition = response["content-disposition"]
+      object
+    end
+
+    def get_object(options = {})
+      response = object_request(:get, options)
+      parse_headers(response)
+    end
+
+    def object_headers(options = {})
+      response = object_request(:head, options)
+      parse_headers(response)
+    rescue Error::ResponseError => e
+      if e.response.code.to_i == 404
+        raise Error::ResponseError.exception("NoSuchKey").new("The specified key does not exist.", nil)
+      else
+        raise e
+      end
+    end
+
+    def put_object
+      body = content.is_a?(IO) ? content.read : content
+      response = object_request(:put, :body => body, :headers => dump_headers)
+      parse_headers(response)
+    end
+
+    def delete_object(options = {})
+      object_request(:delete)
+    end
+
+    def initialize(bucket, options = {})
+      self.bucket = bucket
+      self.key = options[:key]
+      self.last_modified = options[:last_modified]
+      self.etag = options[:etag]
+      self.size = options[:size]
+    end
+
+    def object_request(method, options = {})
+      bucket_request(method, options.merge(:path => key))
+    end
+
+    def last_modified=(last_modified)
+      @last_modified = Time.parse(last_modified) if last_modified
+    end
+
+    def etag=(etag)
+      @etag = etag[1..-2] if etag
+    end
+
+    def key_valid?(key)
+      if (key.nil? or key.empty? or key =~ %r#//#)
+        false
+      else
+        true
+      end
+    end
+
+    def dump_headers
+      headers = {}
+      headers[:x_amz_acl] = @acl || "public-read"
+      headers[:x_amz_storage_class] = @storage_class || "STANDARD"
+      headers[:content_type] = @content_type || "application/octet-stream"
+      headers[:content_encoding] = @content_encoding if @content_encoding
+      headers[:content_disposition] = @content_disposition if @content_disposition
+      headers
+    end
+
+    def parse_headers(response)
+      self.etag = response["etag"]
+      self.content_type = response["content-type"]
+      self.content_disposition = response["content-disposition"]
+      self.content_encoding = response["content-encoding"]
+      self.last_modified = response["last-modified"]
+      if response["content-range"]
+        self.size = response["content-range"].sub(/[^\/]+\//, "").to_i
+      else
+        self.size = response["content-length"]
+        self.content = response.body
+      end
+    end
+  end
+end

data/lib/s3/objects_extension.rb

@@ -0,0 +1,37 @@
+module S3
+  module ObjectsExtension
+    # Builds the object in the bucket with given key
+    def build(key)
+      Object.send(:new, proxy_owner, :key => key)
+    end
+
+    # Finds first object with given name or raises the exception if
+    # not found
+    def find_first(name)
+      object = build(name)
+      object.retrieve
+    end
+    alias :find :find_first
+
+    # Finds the objects in the bucket.
+    #
+    # ==== Options
+    # * <tt>:prefix</tt> - Limits the response to keys which begin
+    #   with the indicated prefix
+    # * <tt>:marker</tt> - Indicates where in the bucket to begin
+    #   listing
+    # * <tt>:max_keys</tt> - The maximum number of keys you'd like
+    #   to see
+    # * <tt>:delimiter</tt> - Causes keys that contain the same
+    #   string between the prefix and the first occurrence of the
+    #   delimiter to be rolled up into a single result element
+    def find_all(options = {})
+      proxy_owner.send(:list_bucket, options)
+    end
+
+    # Destroys all keys in the bucket
+    def destroy_all
+      proxy_target.each { |object| object.destroy }
+    end
+  end
+end

data/lib/s3/parser.rb

@@ -0,0 +1,48 @@
+module S3
+  module Parser
+    include REXML
+
+    def rexml_document(xml)
+      xml.force_encoding(Encoding::UTF_8) if xml.respond_to? :force_encoding
+      Document.new(xml)
+    end
+
+    def parse_list_all_my_buckets_result(xml)
+      names = []
+      rexml_document(xml).elements.each("ListAllMyBucketsResult/Buckets/Bucket/Name") { |e| names << e.text }
+      names
+    end
+
+    def parse_location_constraint(xml)
+      rexml_document(xml).elements["LocationConstraint"].text
+    end
+
+    def parse_list_bucket_result(xml)
+      objects_attributes = []
+      rexml_document(xml).elements.each("ListBucketResult/Contents") do |e|
+        object_attributes = {}
+        object_attributes[:key] = e.elements["Key"].text
+        object_attributes[:etag] = e.elements["ETag"].text
+        object_attributes[:last_modified] = e.elements["LastModified"].text
+        object_attributes[:size] = e.elements["Size"].text
+        objects_attributes << object_attributes
+      end
+      objects_attributes
+    end
+
+    def parse_copy_object_result(xml)
+      object_attributes = {}
+      document = rexml_document(xml)
+      object_attributes[:etag] = document.elements["CopyObjectResult/ETag"].text
+      object_attributes[:last_modified] = document.elements["CopyObjectResult/LastModified"].text
+      object_attributes
+    end
+
+    def parse_error(xml)
+      document = rexml_document(xml)
+      code = document.elements["Error/Code"].text
+      message = document.elements["Error/Message"].text
+      [code, message]
+    end
+  end
+end

data/lib/s3/service.rb

@@ -0,0 +1,82 @@
+module S3
+  class Service
+    include Parser
+    include Proxies
+
+    attr_reader :access_key_id, :secret_access_key, :use_ssl, :proxy
+
+    # Compares service to other, by <tt>access_key_id</tt> and
+    # <tt>secret_access_key</tt>
+    def ==(other)
+      self.access_key_id == other.access_key_id and self.secret_access_key == other.secret_access_key
+    end
+
+    # Creates new service.
+    #
+    # ==== Options
+    # * <tt>:access_key_id</tt> - Access key id (REQUIRED)
+    # * <tt>:secret_access_key</tt> - Secret access key (REQUIRED)
+    # * <tt>:use_ssl</tt> - Use https or http protocol (false by
+    #   default)
+    # * <tt>:debug</tt> - Display debug information on the STDOUT
+    #   (false by default)
+    # * <tt>:timeout</tt> - Timeout to use by the Net::HTTP object
+    #   (60 by default)
+    def initialize(options)
+      @access_key_id = options.fetch(:access_key_id)
+      @secret_access_key = options.fetch(:secret_access_key)
+      @use_ssl = options.fetch(:use_ssl, false)
+      @timeout = options.fetch(:timeout, 60)
+      @debug = options.fetch(:debug, false)
+      
+      raise ArgumentError, "Missing proxy settings. Must specify at least :host." if options[:proxy] && !options[:proxy][:host]
+      @proxy = options.fetch(:proxy, nil)
+    end
+
+    # Returns all buckets in the service and caches the result (see
+    # +reload+)
+    def buckets
+      MethodProxy.new(self, :list_all_my_buckets, :extend => BucketsExtension)
+    end
+
+    # Returns "http://" or "https://", depends on <tt>:use_ssl</tt>
+    # value from initializer
+    def protocol
+      use_ssl ? "https://" : "http://"
+    end
+
+    # Returns 443 or 80, depends on <tt>:use_ssl</tt> value from
+    # initializer
+    def port
+      use_ssl ? 443 : 80
+    end
+
+    def inspect #:nodoc:
+      "#<#{self.class}:#@access_key_id>"
+    end
+
+    private
+
+    def list_all_my_buckets
+      response = service_request(:get)
+      names = parse_list_all_my_buckets_result(response.body)
+      names.map { |name| Bucket.send(:new, self, name) }
+    end
+
+    def service_request(method, options = {})
+      connection.request(method, options.merge(:path => "/#{options[:path]}"))
+    end
+
+    def connection
+      if @connection.nil?
+        @connection = Connection.new(:access_key_id => @access_key_id,
+                                     :secret_access_key => @secret_access_key,
+                                     :use_ssl => @use_ssl,
+                                     :timeout => @timeout,
+                                     :debug => @debug,
+                                     :proxy => @proxy)
+      end
+      @connection
+    end
+  end
+end

data/lib/s3/signature.rb

@@ -0,0 +1,229 @@
+module S3
+
+  # Class responsible for generating signatures to requests.
+  #
+  # Implements algorithm defined by Amazon Web Services to sign
+  # request with secret private credentials
+  #
+  # === See
+  # http://docs.amazonwebservices.com/AmazonS3/latest/index.html?RESTAuthentication.html
+
+  class Signature
+
+    # Generates signature for given parameters
+    #
+    # ==== Options
+    # * <tt>:host</tt> - Hostname
+    # * <tt>:request</tt> - Net::HTTPRequest object with correct
+    #   headers
+    # * <tt>:access_key_id</tt> - Access key id
+    # * <tt>:secret_access_key</tt> - Secret access key
+    #
+    # ==== Returns
+    # Generated signature string for given hostname and request
+    def self.generate(options)
+      request = options[:request]
+      access_key_id = options[:access_key_id]
+
+      options.merge!(:headers => request,
+                     :method => request.method,
+                     :resource => request.path)
+
+      signature = canonicalized_signature(options)
+
+      "AWS #{access_key_id}:#{signature}"
+    end
+
+    # Generates temporary URL signature for given resource
+    #
+    # ==== Options
+    # * <tt>:bucket</tt> - Bucket in which the resource resides
+    # * <tt>:resource</tt> - Path to the resouce you want to create
+    #   a temporary link to
+    # * <tt>:secret_access_key</tt> - Secret access key
+    # * <tt>:expires_at</tt> - Unix time stamp of when the resouce
+    #   link will expire
+    # * <tt>:method</tt> - HTTP request method you want to use on
+    #   the resource, defaults to GET
+    # * <tt>:headers</tt> - Any additional HTTP headers you intend
+    #   to use when requesting the resource
+    def self.generate_temporary_url_signature(options)
+      bucket = options[:bucket]
+      resource = options[:resource]
+      secret_access_key = options[:secret_access_key]
+      expires = options[:expires_at]
+
+      headers = options[:headers] || {}
+      headers.merge!('date' => expires.to_i.to_s)
+
+      options.merge!(:resource => "/#{bucket}/#{resource}",
+                     :method => options[:method] || :get,
+                     :headers => headers)
+      signature = canonicalized_signature(options)
+
+      CGI.escape(signature)
+    end
+
+    # Generates temporary URL for given resource
+    #
+    # ==== Options
+    # * <tt>:bucket</tt> - Bucket in which the resource resides
+    # * <tt>:resource</tt> - Path to the resouce you want to create
+    #   a temporary link to
+    # * <tt>:access_key</tt> - Access key
+    # * <tt>:secret_access_key</tt> - Secret access key
+    # * <tt>:expires_at</tt> - Unix time stamp of when the resouce
+    #   link will expire
+    # * <tt>:method</tt> - HTTP request method you want to use on
+    #   the resource, defaults to GET
+    # * <tt>:headers</tt> - Any additional HTTP headers you intend
+    #   to use when requesting the resource
+    def self.generate_temporary_url(options)
+      bucket = options[:bucket]
+      resource = options[:resource]
+      access_key = options[:access_key]
+      expires = options[:expires_at].to_i
+      signature = generate_temporary_url_signature(options)
+
+      url = "http://#{S3::HOST}/#{bucket}/#{resource}"
+      url << "?AWSAccessKeyId=#{access_key}"
+      url << "&Expires=#{expires}"
+      url << "&Signature=#{signature}"
+    end
+
+    private
+
+    def self.canonicalized_signature(options)
+      headers = options[:headers] || {}
+      host = options[:host] || ""
+      resource = options[:resource]
+      access_key_id = options[:access_key_id]
+      secret_access_key = options[:secret_access_key]
+
+      http_verb = options[:method].to_s.upcase
+      content_md5 = headers["content-md5"] || ""
+      content_type = headers["content-type"] || ""
+      date = headers["x-amz-date"].nil? ? headers["date"] : ""
+      canonicalized_resource = canonicalized_resource(host, resource)
+      canonicalized_amz_headers = canonicalized_amz_headers(headers)
+
+      string_to_sign = ""
+      string_to_sign << http_verb
+      string_to_sign << "\n"
+      string_to_sign << content_md5
+      string_to_sign << "\n"
+      string_to_sign << content_type
+      string_to_sign << "\n"
+      string_to_sign << date
+      string_to_sign << "\n"
+      string_to_sign << canonicalized_amz_headers
+      string_to_sign << canonicalized_resource
+
+      digest = OpenSSL::Digest::Digest.new('sha1')
+      hmac = OpenSSL::HMAC.digest(digest, secret_access_key, string_to_sign)
+      base64 = Base64.encode64(hmac)
+      base64.chomp
+    end
+
+    # Helper method for extracting header fields from Net::HTTPRequest
+    # and preparing them for singing in #generate method
+    #
+    # ==== Parameters
+    # * <tt>request</tt> - Net::HTTPRequest object with header fields
+    #   filled in
+    #
+    # ==== Returns
+    # String containing interesting header fields in suitable order
+    # and form
+    def self.canonicalized_amz_headers(request)
+      headers = []
+
+      # 1. Convert each HTTP header name to lower-case. For example,
+      # 'X-Amz-Date' becomes 'x-amz-date'.
+      request.each { |key, value| headers << [key.downcase, value] if key =~ /\Ax-amz-/io }
+      #=> [["c", 0], ["a", 1], ["a", 2], ["b", 3]]
+
+      # 2. Sort the collection of headers lexicographically by header
+      # name.
+      headers.sort!
+      #=> [["a", 1], ["a", 2], ["b", 3], ["c", 0]]
+
+      # 3. Combine header fields with the same name into one
+      # "header-name:comma-separated-value-list" pair as prescribed by
+      # RFC 2616, section 4.2, without any white-space between
+      # values. For example, the two metadata headers
+      # 'x-amz-meta-username: fred' and 'x-amz-meta-username: barney'
+      # would be combined into the single header 'x-amz-meta-username:
+      # fred,barney'.
+      combined_headers = headers.inject([]) do |new_headers, header|
+        existing_header = new_headers.find { |h| h.first == header.first }
+        if existing_header
+          existing_header.last << ",#{header.last}"
+        else
+          new_headers << header
+        end
+      end
+      #=> [["a", "1,2"], ["b", "3"], ["c", "0"]]
+
+      # 4. "Un-fold" long headers that span multiple lines (as allowed
+      # by RFC 2616, section 4.2) by replacing the folding white-space
+      # (including new-line) by a single space.
+      unfolded_headers = combined_headers.map do |header|
+        key = header.first
+        value = header.last
+        value.gsub!(/\s+/, " ")
+        [key, value]
+      end
+
+      # 5. Trim any white-space around the colon in the header. For
+      # example, the header 'x-amz-meta-username: fred,barney' would
+      # become 'x-amz-meta-username:fred,barney'
+      joined_headers = unfolded_headers.map do |header|
+        key = header.first.strip
+        value = header.last.strip
+        "#{key}:#{value}"
+      end
+
+      # 6. Finally, append a new-line (U+000A) to each canonicalized
+      # header in the resulting list. Construct the
+      # CanonicalizedResource element by concatenating all headers in
+      # this list into a single string.
+      joined_headers << "" unless joined_headers.empty?
+      joined_headers.join("\n")
+    end
+
+    # Helper methods for extracting caninocalized resource address
+    #
+    # ==== Parameters
+    # * <tt>host</tt> - Hostname
+    # * <tt>request</tt> - Net::HTTPRequest object with header fields
+    #   filled in
+    #
+    # ==== Returns
+    # String containing extracted canonicalized resource
+    def self.canonicalized_resource(host, resource)
+      # 1. Start with the empty string ("").
+      string = ""
+
+      # 2. If the request specifies a bucket using the HTTP Host
+      # header (virtual hosted-style), append the bucket name preceded
+      # by a "/" (e.g., "/bucketname"). For path-style requests and
+      # requests that don't address a bucket, do nothing. For more
+      # information on virtual hosted-style requests, see Virtual
+      # Hosting of Buckets.
+      bucket_name = host.sub(/\.?s3\.amazonaws\.com\Z/, "")
+      string << "/#{bucket_name}" unless bucket_name.empty?
+
+      # 3. Append the path part of the un-decoded HTTP Request-URI,
+      # up-to but not including the query string.
+      uri = URI.parse(resource)
+      string << uri.path
+
+      # 4. If the request addresses a sub-resource, like ?location,
+      # ?acl, or ?torrent, append the sub-resource including question
+      # mark.
+      string << "?#{$1}" if uri.query =~ /&?(acl|torrent|logging|location)(?:&|=|\Z)/
+      string
+    end
+  end
+end

data/lib/s3/version.rb

@@ -0,0 +1,3 @@
+module S3
+  VERSION = "0.3.2"
+end

data/lib/s3.rb

@@ -0,0 +1,26 @@
+require "base64"
+require "cgi"
+require "digest/md5"
+require "forwardable"
+require "net/http"
+require "net/https"
+require "openssl"
+require "rexml/document"
+require "time"
+
+require "proxies"
+require "s3/objects_extension"
+require "s3/buckets_extension"
+require "s3/parser"
+require "s3/bucket"
+require "s3/connection"
+require "s3/exceptions"
+require "s3/object"
+require "s3/service"
+require "s3/signature"
+require "s3/version"
+
+module S3
+  # Default (and only) host serving S3 stuff
+  HOST = "s3.amazonaws.com"
+end