s3 0.2.4 → 0.2.5

data/.gitignore

@@ -4,4 +4,4 @@ coverage
 rdoc
 pkg
 *.gem
-*.gemspec
+

data/Rakefile

@@ -8,12 +8,13 @@ begin
   Jeweler::Tasks.new do |gem|
     gem.name = "s3"
     gem.summary = %Q{Library for accessing S3 objects and buckets, with command line tool}
+    gem.description = %Q{S3 library provides access to Amazon's Simple Storage Service. It supports both: European and US buckets through REST API.}
     gem.email = "qoobaa@gmail.com"
     gem.homepage = "http://jah.pl/projects/s3.html"
     gem.authors = ["Jakub Kuźma", "Mirosław Boruta"]
     gem.add_dependency "trollop", ">=1.14"
     gem.add_development_dependency "test-unit", ">= 2.0"
-    gem.add_development_dependency "rr", "=0.10.2"
+    gem.add_development_dependency "mocha"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
 

data/VERSION

@@ -1 +1 @@
-0.2.4
+0.2.5

data/lib/s3.rb

@@ -1,4 +1,5 @@
 require "base64"
+require "cgi"
 require "digest/md5"
 require "forwardable"
 require "net/http"

data/lib/s3/bucket.rb

@@ -26,15 +26,15 @@ module S3
       end
     end
 
-    # Compares the bucket with other bucket. Returns true if the key
-    # of the objects are the same, and both have the same buckets (see
-    # bucket equality)
+    # Compares the bucket with other bucket. Returns true if the names
+    # of the buckets are the same, and both have the same services
+    # (see Service equality)
     def ==(other)
       self.name == other.name and self.service == other.service
     end
 
-    # Similar to retrieve, but catches NoSuchBucket exceptions and
-    # returns false instead.
+    # Similar to retrieve, but catches S3::Error::NoSuchBucket
+    # exceptions and returns false instead.
     def exists?
       retrieve
       true
@@ -42,9 +42,9 @@ module S3
       false
     end
 
-    # Destroys given bucket. Raises an BucketNotEmpty exception if the
-    # bucket is not empty. You can destroy non-empty bucket passing
-    # true (to force destroy)
+    # Destroys given bucket. Raises an S3::Error::BucketNotEmpty
+    # exception if the bucket is not empty. You can destroy non-empty
+    # bucket passing true (to force destroy)
     def destroy(force = false)
       delete_bucket
       true
@@ -58,33 +58,32 @@ module S3
     end
 
     # Saves the newly built bucket. Optionally you can pass location
-    # of the bucket (:eu or :us)
+    # of the bucket (<tt>:eu</tt> or <tt>:us</tt>)
     def save(location = nil)
       create_bucket_configuration(location)
       true
     end
 
-    # Returns true if the name of the bucket can be used like VHOST
+    # Returns true if the name of the bucket can be used like +VHOST+
     # name. If the bucket contains characters like underscore it can't
-    # be used as VHOST (e.g. bucket_name.s3.amazonaws.com)
+    # be used as +VHOST+ (e.g. <tt>bucket_name.s3.amazonaws.com</tt>)
     def vhost?
       "#@name.#{HOST}" =~ /\A#{URI::REGEXP::PATTERN::HOSTNAME}\Z/
     end
 
-    # Returns host name of the bucket according (see vhost?)
+    # Returns host name of the bucket according (see #vhost? method)
     def host
       vhost? ? "#@name.#{HOST}" : "#{HOST}"
     end
 
-    # Returns path prefix for non VHOST bucket. Path prefix is used
-    # instead of VHOST name,
-    # e.g. "bucket_name/"
+    # Returns path prefix for non +VHOST+ bucket. Path prefix is used
+    # instead of +VHOST+ name, e.g. "bucket_name/"
     def path_prefix
       vhost? ? "" : "#@name/"
     end
 
     # Returns the objects in the bucket and caches the result (see
-    # reload).
+    # #reload method).
     def objects(reload = false)
       if reload or @objects.nil?
         @objects = list_bucket
@@ -109,11 +108,17 @@ module S3
       alias :find :find_first
 
       # Finds the objects in the bucket.
-      # ==== Options:
-      # +prefix+:: Limits the response to keys which begin with the indicated prefix
-      # +marker+:: Indicates where in the bucket to begin listing
-      # +max_keys+:: The maximum number of keys you'd like to see
-      # +delimiter+:: 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
+      #
+      # ==== 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

data/lib/s3/connection.rb

@@ -7,46 +7,52 @@ module S3
     attr_accessor :access_key_id, :secret_access_key, :use_ssl, :timeout, :debug
     alias :use_ssl? :use_ssl
 
-    # ==== Parameters:
-    # +options+:: Hash of options
+    # Creates new connection object.
     #
-    # ==== Options:
-    # +access_key_id+:: access key id
-    # +secret_access_key+:: secret access key
-    # +use_ssl+:: optional, defaults to false
-    # +debug+:: optional, defaults to false
-    # +timeout+:: optional, for Net::HTTP
+    # ==== 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[:access_key_id]
-      @secret_access_key = options[:secret_access_key]
-      @use_ssl = options[:use_ssl] || false
-      @debug = options[:debug]
-      @timeout = options[:timeout]
+      @access_key_id = options.fetch(:access_key_id)
+      @secret_access_key = options.fetch(:secret_access_key)
+      @use_ssl = options.fetch(:use_ssl, false)
+      @debug = options.fetch(:debug, false)
+      @timeout = options.fetch(:timeout, 60)
     end
 
     # Makes request with given HTTP method, sets missing parameters,
     # adds signature to request header and returns response object
     # (Net::HTTPResponse)
     #
-    # ==== Parameters:
-    # +method+:: HTTP Method symbol, can be :get, :put, :delete
-    # +options+:: hash of options
+    # ==== Parameters
+    # * <tt>method</tt> - HTTP Method symbol, can be <tt>:get</tt>,
+    #   <tt>:put</tt>, <tt>:delete</tt>
     #
     # ==== Options:
-    # +host+:: hostname to connecto to, optional, defaults to s3.amazonaws.com[s3.amazonaws.com]
-    # +path+:: path to send request to, required, throws ArgumentError if not given
-    # +body+:: request body, only meaningful for :put request
-    # +params+:: parameters to add to query string for request, can be String or Hash
-    # +headers+:: Hash of headers fields to add to request header
+    # * <tt>:host</tt> - Hostname to connecto to, defaults
+    #   to <tt>s3.amazonaws.com</tt>
+    # * <tt>:path</tt> - path to send request to (REQUIRED)
+    # * <tt>:body</tt> - Request body, only meaningful for
+    #   <tt>:put</tt> request
+    # * <tt>:params</tt> - Parameters to add to query string for
+    #   request, can be String or Hash
+    # * <tt>:headers</tt> - Hash of headers fields to add to request
+    #   header
     #
-    # ==== Returns:
-    # Net::HTTPResponse object -- response from remote server
+    # ==== Returns
+    # Net::HTTPResponse object -- response from the server
     def request(method, options)
-      host = options[:host] || HOST
-      path = options[:path] or raise ArgumentError.new("no path given")
-      body = options[:body]
-      params = options[:params]
-      headers = options[:headers]
+      host = options.fetch(:host, HOST)
+      path = options.fetch(:path)
+      body = options.fetch(:body, "")
+      params = options.fetch(:params, {})
+      headers = options.fetch(:headers, {})
 
       if params
         params = params.is_a?(String) ? params : self.class.parse_params(params)
@@ -66,13 +72,13 @@ module S3
       send_request(host, request)
     end
 
-    # Helper function to parser parameters and create single string of params
-    # added to questy string
+    # Helper function to parser parameters and create single string of
+    # params added to questy string
     #
-    # ==== Parameters:
-    # +params+: Hash of parameters if form <tt>key => value|nil</tt>
+    # ==== Parameters
+    # * <tt>params</tt> - Hash of parameters
     #
-    # ==== Returns:
+    # ==== Returns
     # String -- containing all parameters joined in one params string,
     # i.e. <tt>param1=val&param2&param3=0</tt>
     def self.parse_params(params)
@@ -96,14 +102,14 @@ module S3
     # Helper function to change headers from symbols, to in correct
     # form (i.e. with '-' instead of '_')
     #
-    # ==== Parameters:
-    # +headers+:: Hash of pairs <tt>headername => value</tt>,
-    #             where value can be Range (for Range header) or any other
-    #             value which can be translated to string
+    # ==== Parameters
+    # * <tt>headers</tt> - Hash of pairs <tt>headername => value</tt>,
+    #   where value can be Range (for Range header) or any other value
+    #   which can be translated to string
     #
-    # ==== Returns:
-    # Hash of headers translated from symbol to string,
-    # containing only interesting headers
+    # ==== Returns
+    # Hash of headers translated from symbol to string, containing
+    # only interesting headers
     def self.parse_headers(headers)
       interesting_keys = [:content_type, :x_amz_acl, :range,
                           :if_modified_since, :if_unmodified_since,
@@ -170,9 +176,9 @@ module S3
         end
 
         request["Authorization"] = Signature.generate(:host => host,
-                                                          :request => request,
-                                                          :access_key_id => access_key_id,
-                                                          :secret_access_key => secret_access_key)
+                                                      :request => request,
+                                                      :access_key_id => access_key_id,
+                                                      :secret_access_key => secret_access_key)
         http.request(request)
       end
 

data/lib/s3/exceptions.rb

@@ -12,23 +12,25 @@ module S3
     class ResponseError < StandardError
       attr_reader :response
 
-      # ==== Parameters:
-      # +message+:: what went wrong
-      # +response+:: Net::HTTPResponse object or nil
+      # Creates new S3::ResponseError.
+      #
+      # ==== Parameters
+      # * <tt>message</tt> - what went wrong
+      # * <tt>response</tt> - Net::HTTPResponse object or nil
       def initialize(message, response)
         @response = response
         super(message)
       end
 
-      # Factory for all other Exception classes in module, each for every
-      # error response available from AmazonAWS
+      # Factory for all other Exception classes in module, each for
+      # every error response available from AmazonAWS
       #
-      # ==== Parameters:
-      # +code+:: code name of exception
+      # ==== Parameters
+      # * <tt>code</tt> - Code name of exception
       #
-      # ==== Returns:
-      # Descendant of ResponseError suitable for that exception code or ResponseError class
-      # if no class found
+      # ==== Returns
+      # Descendant of ResponseError suitable for that exception code
+      # or ResponseError class if no class found
       def self.exception(code)
         S3::Error.const_get(code)
       rescue NameError

data/lib/s3/object.rb

@@ -10,17 +10,17 @@ module S3
     attr_writer :content
 
     def_instance_delegators :bucket, :name, :service, :bucket_request, :vhost?, :host, :path_prefix
-    def_instance_delegators :service, :protocol, :port
+    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)
+    # Bucket equality)
     def ==(other)
       self.key == other.key and self.bucket == other.bucket
     end
 
-    # Returns full key of the object: e.g. +bucket-name/object/key.ext+
+    # Returns full key of the object: e.g. <tt>bucket-name/object/key.ext</tt>
     def full_key
       [name, key].join("/")
     end
@@ -34,6 +34,7 @@ module S3
 
     # 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)
@@ -41,17 +42,17 @@ module S3
     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
+    # 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
       get_object(:headers => { :range => 0..0 })
       self
     end
 
-    # Retrieves the object from the server, returns true if the
-    # object exists or false otherwise. Uses retrieve method, but
-    # catches NoSuchKey exception and returns false when it happens
+    # 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
@@ -75,11 +76,15 @@ module S3
     end
 
     # Copies the file to another key and/or bucket.
-    # ==== Options:
-    # +key+:: new key to store object in
-    # +bucket+:: new bucket to store object in (instance of S3::Bucket)
-    # +acl+:: acl of the copied object (default: "public-read")
-    # +content_type+:: content type of the copied object (default: "application/octet-stream")
+    #
+    # ==== 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
@@ -90,16 +95,28 @@ module S3
       true
     end
 
-    # Returns Object's URL using protocol specified in Service,
-    # e.g. http://domain.com.s3.amazonaws.com/key/with/path.extension
+    # 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 Object's CNAME URL (without s3.amazonaws.com suffix)
-    # using protocol specified in Service,
-    # e.g. http://domain.com/key/with/path.extension. (you have to set
-    # the CNAME in your DNS before you use the CNAME URL schema).
+    # 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_on => expires_at,
+                                                             :secret_access_key => secret_access_key)
+
+      "#{url}?Signature=#{URI.escape(signature)}&Expires=#{URI.escape(expires_at.to_i)}"
+    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

data/lib/s3/service.rb

@@ -5,29 +5,33 @@ module S3
 
     attr_reader :access_key_id, :secret_access_key, :use_ssl
 
-    # Compares service to other, by access_key_id and secret_access_key
+    # 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
 
-    # ==== Parameters:
-    # +options+:: a hash of options described below
+    # Creates new service.
     #
-    # ==== Options:
-    # +access_key_id+:: Amazon access key id, required
-    # +secret_access_key+:: Amazon secret access key, required
-    # +use_ssl+:: true if use ssl in connection, otherwise false
-    # +timeout+:: parameter for Net::HTTP module
-    # +debug+:: prints the raw requests to STDOUT
+    # ==== 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[:access_key_id] or raise ArgumentError, "No access key id given"
-      @secret_access_key = options[:secret_access_key] or raise ArgumentError, "No secret access key given"
-      @use_ssl = options[:use_ssl]
-      @timeout = options[:timeout]
-      @debug = options[:debug]
+      @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)
     end
 
-    # Returns all buckets in the service and caches the result (see reload)
+    # Returns all buckets in the service and caches the result (see
+    # +reload+)
     def buckets(reload = false)
       if reload or @buckets.nil?
         @buckets = list_all_my_buckets
@@ -36,12 +40,14 @@ module S3
       end
     end
 
-    # Returns "http://" or "https://", depends on use_ssl value from initializer
+    # Returns "http://" or "https://", depends on <tt>:use_ssl</tt>
+    # value from initializer
     def protocol
       use_ssl ? "https://" : "http://"
     end
 
-    # Return 443 or 80, depends on use_ssl value from initializer
+    # Returns 443 or 80, depends on <tt>:use_ssl</tt> value from
+    # initializer
     def port
       use_ssl ? 443 : 80
     end
@@ -97,12 +103,11 @@ module S3
 
     def connection
       if @connection.nil?
-        @connection = Connection.new
-        @connection.access_key_id = @access_key_id
-        @connection.secret_access_key = @secret_access_key
-        @connection.use_ssl = @use_ssl
-        @connection.timeout = @timeout
-        @connection.debug = @debug
+        @connection = Connection.new(:access_key_id => @access_key_id,
+                                     :secret_access_key => @secret_access_key,
+                                     :use_ssl => @use_ssl,
+                                     :timeout => @timeout,
+                                     :debug => @debug)
       end
       @connection
     end