seanwalbran-scashin133-s3 0.3.11

data/.gitignore

@@ -0,0 +1,7 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/Gemfile.lock

@@ -0,0 +1,23 @@
+PATH
+  remote: .
+  specs:
+    scashin133-s3 (0.3.11)
+      proxies (~> 0.2.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    mocha (0.9.8)
+      rake
+    proxies (0.2.1)
+    rake (0.8.7)
+    test-unit (2.1.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.0.0)
+  mocha
+  scashin133-s3!
+  test-unit (>= 2.0)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Jakub Kuźma, Mirosław Boruta
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,79 @@
+= S3
+
+S3 library provides access to {Amazon's Simple Storage Service}[http://aws.amazon.com/s3/].
+
+It supports both: European and US buckets through the {REST API}[http://docs.amazonwebservices.com/AmazonS3/latest/API/APIRest.html].
+
+== Installation
+
+    gem install s3
+
+== Usage
+
+=== Initialize the service
+
+    require "s3"
+    service = S3::Service.new(:access_key_id => "...",
+                              :secret_access_key => "...")
+    #=> #<S3::Service:...>
+
+=== List buckets
+
+    service.buckets
+    #=> [#<S3::Bucket:first-bucket>,
+    #    #<S3::Bucket:second-bucket>]
+
+=== Find bucket
+
+    first_bucket = service.buckets.find("first-bucket")
+    #=> #<S3::Bucket:first-bucket>
+
+=== List objects in a bucket
+
+    first_bucket.objects
+    #=> [#<S3::Object:/first-bucket/lenna.png>,
+    #    #<S3::Object:/first-bucket/lenna_mini.png>]
+
+=== Find object in a bucket
+
+    object = first_bucket.objects.find("lenna.png")
+    #=> #<S3::Object:/first-bucket/lenna.png>
+
+=== Access object metadata (cached from find)
+
+    object.content_type
+    #=> "image/png"
+
+=== Access object content (downloads the object)
+
+    object.content
+    #=> "\x89PNG\r\n\x1A\n\x00\x00\x00\rIHDR\x00..."
+
+=== Delete an object
+
+    object.destroy
+    #=> true
+
+=== Create an object
+
+    new_object = bucket.objects.build("bender.png")
+    #=> #<S3::Object:/synergy-staging/bender.png>
+
+    new_object.content = open("bender.png")
+
+    new_object.save
+    #=> true
+
+Please note that new objects are created with "public-read" ACL by
+default.
+
+== See also
+
+* rubygems[http://rubygems.org/gems/s3]
+* repository[http://github.com/qoobaa/s3]
+* {issue tracker}[http://github.com/qoobaa/s3/issues]
+* documentation[http://rubydoc.info/github/qoobaa/s3/master/frames]
+
+== Copyright
+
+Copyright (c) 2009 Jakub Kuźma, Mirosław Boruta. See LICENSE[http://github.com/qoobaa/s3/raw/master/LICENSE] for details.

data/Rakefile

@@ -0,0 +1,21 @@
+require "bundler"
+Bundler::GemHelper.install_tasks
+Bundler.setup
+
+require "rake/testtask"
+require "rake/rdoctask"
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << "lib" << "test"
+  test.pattern = "test/**/*_test.rb"
+  test.verbose = true
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title = "s3 #{S3::VERSION}"
+  rdoc.rdoc_files.include("README.rdoc")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+task :default => :test

data/lib/s3.rb

@@ -0,0 +1,27 @@
+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/request"
+require "s3/service"
+require "s3/signature"
+require "s3/version"
+
+module S3
+  # Default (and only) host serving S3 stuff
+  HOST = "s3.amazonaws.com"
+end

data/lib/s3/bucket.rb

@@ -0,0 +1,182 @@
+module S3
+  class Bucket
+    include Parser
+    include Proxies
+    extend Forwardable
+
+    attr_reader :name, :service
+
+    def_instance_delegators :service, :service_request
+    private_class_method :new
+
+    # Retrieves the bucket information from the server. Raises an
+    # S3::Error exception if the bucket doesn't exist or you don't
+    # have access to it, etc.
+    def retrieve
+      bucket_headers
+      self
+    end
+
+    # Returns location of the bucket, e.g. "EU"
+    def location(reload = false)
+      return @location if defined?(@location) and not reload
+      @location = location_constraint
+    end
+
+    # 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 S3::Error::NoSuchBucket
+    # exceptions and returns false instead.
+    def exists?
+      retrieve
+      true
+    rescue Error::NoSuchBucket
+      false
+    end
+
+    # 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
+    rescue Error::BucketNotEmpty
+      if force
+        objects.destroy_all
+        retry
+      else
+        raise
+      end
+    end
+
+    # Saves the newly built bucket.
+    #
+    # ==== Options
+    # * <tt>:location</tt> - location of the bucket
+    #   (<tt>:eu</tt> or <tt>us</tt>)
+    # * Any other options are passed through to
+    #   Connection#request
+    def save(options = {})
+      options = {:location => options} unless options.is_a?(Hash)
+      create_bucket_configuration(options)
+      true
+    end
+
+    # 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. <tt>bucket_name.s3.amazonaws.com</tt>)
+    def vhost?
+      self.class.vhost?(@name)
+    end
+
+    # 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/"
+    def path_prefix
+      vhost? ? "" : "#@name/"
+    end
+
+    # Returns the objects in the bucket and caches the result
+    def objects
+      Proxy.new(lambda { list_bucket }, :owner => self, :extend => ObjectsExtension)
+    end
+
+    # Returns the object with the given key. Does not check whether the
+    # object exists. But also does not issue any HTTP requests, so it's
+    # much faster than objects.find
+    def object(key)
+      Object.send(:new, self, :key => key)
+    end
+
+    def inspect #:nodoc:
+      "#<#{self.class}:#{name}>"
+    end
+    
+    def self.vhost?(name)
+      "#{name}.#{HOST}" =~ /\A#{URI::REGEXP::PATTERN::HOSTNAME}\Z/
+    end
+
+    private
+
+    attr_writer :service
+
+    def location_constraint
+      response = bucket_request(:get, :params => {:location => nil})
+      parse_location_constraint(response.body)
+    end
+
+    def list_bucket(options = {})
+      response = bucket_request(:get, :params => options)
+      max_keys = options[:max_keys]
+      objects_attributes = parse_list_bucket_result(response.body)
+
+      # If there are more than 1000 objects S3 truncates listing and
+      # we need to request another listing for the remaining objects.
+      while parse_is_truncated(response.body)
+        next_request_options = {:marker => objects_attributes.last[:key]}
+
+        if max_keys
+          break if objects_attributes.length >= max_keys
+          next_request_options[:max_keys] = max_keys - objects_attributes.length
+        end
+
+        response = bucket_request(:get, :params => options.merge(next_request_options))
+        objects_attributes += parse_list_bucket_result(response.body)
+      end
+
+      objects_attributes.map { |object_attributes| Object.send(:new, self, object_attributes) }
+    end
+
+    def bucket_headers(options = {})
+      response = bucket_request(:head, :params => options)
+    rescue Error::ResponseError => e
+      if e.response.code.to_i == 404
+        raise Error::ResponseError.exception("NoSuchBucket").new("The specified bucket does not exist.", nil)
+      else
+        raise e
+      end
+    end
+
+    def create_bucket_configuration(options = {})
+      location = options[:location].to_s.upcase if options[:location]
+      options[:headers] ||= {}
+      if location and location != "US"
+        options[:body] = "<CreateBucketConfiguration><LocationConstraint>#{location}</LocationConstraint></CreateBucketConfiguration>"
+        options[:headers][:content_type] = "application/xml"
+      end
+      bucket_request(:put, options)
+    end
+
+    def delete_bucket
+      bucket_request(:delete)
+    end
+
+    def initialize(service, name) #:nodoc:
+      self.service = service
+      self.name = name
+    end
+
+    def name=(name)
+      raise ArgumentError.new("Invalid bucket name: #{name}") unless name_valid?(name)
+      @name = name
+    end
+
+    def bucket_request(method, options = {})
+      path = "#{path_prefix}#{options[:path]}"
+      service_request(method, options.merge(:host => host, :path => path))
+    end
+
+    def name_valid?(name)
+      name =~ /\A[a-z0-9][a-z0-9\._-]{2,254}\Z/i and name !~ /\A#{URI::REGEXP::PATTERN::IPV4ADDR}\Z/
+    end
+  end
+end

data/lib/s3/buckets_extension.rb

@@ -0,0 +1,26 @@
+module S3
+  module BucketsExtension
+    # Builds new bucket with given name
+    def build(name)
+      Bucket.send(:new, proxy_owner, name)
+    end
+
+    # Finds the bucket with given name
+    def find_first(name)
+      bucket = build(name)
+      bucket.retrieve
+    end
+    alias :find :find_first
+
+    # Finds all buckets in the service
+    def find_all
+      proxy_target
+    end
+
+    # Destroys all buckets in the service. Doesn't destroy non-empty
+    # buckets by default, pass true to force destroy (USE WITH CARE!).
+    def destroy_all(force = false)
+      proxy_target.each { |bucket| bucket.destroy(force) }
+    end
+  end
+end

data/lib/s3/connection.rb

@@ -0,0 +1,225 @@
+module S3
+
+  # Class responsible for handling connections to amazon hosts
+  class Connection
+    include Parser
+
+    attr_accessor :access_key_id, :secret_access_key, :use_ssl, :timeout, :debug, :proxy
+    alias :use_ssl? :use_ssl
+
+    # Creates new connection object.
+    #
+    # ==== 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)
+    # * <tt>:proxy</tt> - Hash for Net::HTTP Proxy settings
+    #   { :host => "proxy.mydomain.com", :port => "80, :user => "user_a", :password => "secret" }
+    # * <tt>:proxy</tt> - Hash for Net::HTTP Proxy settings
+    # * <tt>:chunk_size</tt> - Size of a chunk when streaming
+    #   (1048576 (1 MiB) 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)
+      @debug = options.fetch(:debug, false)
+      @timeout = options.fetch(:timeout, 60)
+      @proxy = options.fetch(:proxy, nil)
+      @chunk_size = options.fetch(:chunk_size, 1048576)
+    end
+
+    # Makes request with given HTTP method, sets missing parameters,
+    # adds signature to request header and returns response object
+    # (Net::HTTPResponse)
+    #
+    # ==== Parameters
+    # * <tt>method</tt> - HTTP Method symbol, can be <tt>:get</tt>,
+    #   <tt>:put</tt>, <tt>:delete</tt>
+    #
+    # ==== Options:
+    # * <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 the server
+    def request(method, options)
+      host = options.fetch(:host, HOST)
+      path = options.fetch(:path)
+      body = options.fetch(:body, nil)
+      params = options.fetch(:params, {})
+      headers = options.fetch(:headers, {})
+
+      # Must be done before adding params
+      # Encodes all characters except forward-slash (/) and explicitly legal URL characters
+      path = URI.escape(path, /[^#{URI::REGEXP::PATTERN::UNRESERVED}\/]/)
+
+      if params
+        params = params.is_a?(String) ? params : self.class.parse_params(params)
+        path << "?#{params}"
+      end
+
+      request = Request.new(@chunk_size, method.to_s.upcase, !!body, method.to_s.upcase != "HEAD", path)
+
+      headers = self.class.parse_headers(headers)
+      headers.each do |key, value|
+        request[key] = value
+      end
+
+      if body
+        if body.respond_to?(:read)
+          request.body_stream = body
+        else
+          request.body = body
+        end
+        request.content_length = body.respond_to?(:lstat) ? body.stat.size : body.size
+      end
+
+      send_request(host, request)
+    end
+
+    # Helper function to parser parameters and create single string of
+    # params added to questy string
+    #
+    # ==== Parameters
+    # * <tt>params</tt> - Hash of parameters
+    #
+    # ==== Returns
+    # String -- containing all parameters joined in one params string,
+    # i.e. <tt>param1=val&param2&param3=0</tt>
+    def self.parse_params(params)
+      interesting_keys = [:max_keys, :prefix, :marker, :delimiter, :location]
+
+      result = []
+      params.each do |key, value|
+        if interesting_keys.include?(key)
+          parsed_key = key.to_s.gsub("_", "-")
+          case value
+          when nil
+            result << parsed_key
+          else
+            result << "#{parsed_key}=#{value}"
+          end
+        end
+      end
+      result.join("&")
+    end
+
+    # Helper function to change headers from symbols, to in correct
+    # form (i.e. with '-' instead of '_')
+    #
+    # ==== 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
+    def self.parse_headers(headers)
+      interesting_keys = [:content_type, :cache_control, :x_amz_acl, :x_amz_storage_class, :range,
+                          :if_modified_since, :if_unmodified_since,
+                          :if_match, :if_none_match,
+                          :content_disposition, :content_encoding,
+                          :x_amz_copy_source, :x_amz_metadata_directive,
+                          :x_amz_copy_source_if_match,
+                          :x_amz_copy_source_if_none_match,
+                          :x_amz_copy_source_if_unmodified_since,
+                          :x_amz_copy_source_if_modified_since]
+
+      parsed_headers = {}
+      if headers
+        headers.each do |key, value|
+          if interesting_keys.include?(key)
+            parsed_key = key.to_s.gsub("_", "-")
+            parsed_value = value
+            case value
+            when Range
+              parsed_value = "bytes=#{value.first}-#{value.last}"
+            end
+            parsed_headers[parsed_key] = parsed_value
+          end
+        end
+      end
+      parsed_headers
+    end
+
+    private
+
+    def port
+      use_ssl ? 443 : 80
+    end
+
+    def proxy_settings
+      @proxy.values_at(:host, :port, :user, :password) unless @proxy.nil? || @proxy.empty?
+    end
+
+    def http(host)
+      http = Net::HTTP.new(host, port, *proxy_settings)
+      http.set_debug_output(STDOUT) if @debug
+      http.use_ssl = @use_ssl
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE if @use_ssl
+      http.read_timeout = @timeout if @timeout
+      http
+    end
+
+    def send_request(host, request, skip_authorization = false)
+      response = http(host).start do |http|
+        host = http.address
+
+        request["Date"] ||= Time.now.httpdate
+
+        if request.body
+          request["Content-Type"] ||= "application/octet-stream"
+          request["Content-MD5"] = Base64.encode64(Digest::MD5.digest(request.body)).chomp unless request.body.empty?
+        end
+
+        unless skip_authorization
+          request["Authorization"] = Signature.generate(:host => host,
+                                                        :request => request,
+                                                        :access_key_id => access_key_id,
+                                                        :secret_access_key => secret_access_key)
+        end
+
+        http.request(request)
+      end
+
+      if response.code.to_i == 307
+        if response.body
+          doc = Document.new response.body
+          send_request(doc.elements["Error"].elements["Endpoint"].text, request, true)
+        end
+      else
+        handle_response(response)
+      end
+    end
+
+    def handle_response(response)
+      case response.code.to_i
+      when 200...300
+        response
+      when 300...600
+        if response.body.nil? || response.body.empty?
+          raise Error::ResponseError.new(nil, response)
+        else
+          code, message = parse_error(response.body)
+          raise Error::ResponseError.exception(code).new(message, response)
+        end
+      else
+        raise(ConnectionError.new(response, "Unknown response code: #{response.code}"))
+      end
+      response
+    end
+  end
+end