class AWS::S3::Client

Provides a low-level client to Amazon S3:

Each method makes exactly one request to S3, and no two methods make the same type of request.

These methods hide the details of how request parameters are sent to S3; for example:

client.set_bucket_acl(# controls which host to connect to
                      :bucket_name => "mybucket",
                      # the request payload
                      :acl => [{ :grantee => "..." }])

These methods return subclasses of Response, so that you can always get access to the request that was made and the raw HTTP response. You can also access S3-specific response metadata. For example:

response = client.list_buckets
response.http_request.http_method # => "GET"
response.http_response.body  # => "<ListAllMyBucketsResult xmlns..."
response.request_id          # => "32FE2CEB32F5EE25"
                             # (S3-specific metadata)

This client attempts to raise ArgumentError for any invalid requests it can detect before sending a request to the service. For example:

begin
  client.create_bucket
rescue ArgumentError => e
  puts e                     # prints "The bucket_name parameter is
                             # required"
end

Each method can take an :async to turn it into an asynchronous operation. Instead of blocking on the response to the service call, the method will return a handle on the response. For example:
```
response = client.list_buckets(:async => true)
response.on_success { p response.buckets.map(&:name) }
```

@private

Constants

API_VERSION
EMPTY_BODY_ERRORS
XMLNS

Protected Class Methods

bucket_method(method_name, verb, *args, &block) click to toggle source

# File lib/aws/s3/client.rb, line 89
def self.bucket_method(method_name, verb, *args, &block)
  method_options = (args.pop if args.last.kind_of?(Hash)) || {}
  xml_grammar = (args.pop if args.last.respond_to?(:parse))
  verb = verb.to_s.upcase
  subresource = args.first

  add_client_request_method(method_name, :xml_grammar => xml_grammar) do

    configure_request do |req, options|
        require_bucket_name!(options[:bucket_name])
      req.http_method = verb
      req.bucket = options[:bucket_name]
      req.add_param(subresource) if subresource

      if header_options = method_options[:header_options]
        header_options.each do |(option_name, header)|
          req.headers[header] = options[option_name] if
            options[option_name]
        end
      end

    end

    instance_eval(&block) if block
  end
end

object_method(method_name, verb, *args, &block) click to toggle source

# File lib/aws/s3/client.rb, line 117
def self.object_method(method_name, verb, *args, &block)
  bucket_method(method_name, verb, *args) do
    configure_request do |req, options|
      validate_key!(options[:key])
      super(req, options)
      req.key = options[:key]
    end

    instance_eval(&block) if block
  end
end

Public Instance Methods

add_sse_to_response(response) click to toggle source

# File lib/aws/s3/client.rb, line 972
def add_sse_to_response(response)
  sse = nil
  if value = response.http_response.header('x-amz-server-side-encryption')
    sse = value.downcase.to_sym
  end
  Core::MetaUtils.extend_method(response, :server_side_encryption) { sse }
end

extract_error_code(response) click to toggle source

# File lib/aws/s3/client.rb, line 930
def extract_error_code response
  if (response.http_response.status >= 300 ||
      response.request_type == :complete_multipart_upload) and
      body = response.http_response.body and
      parse = Core::XmlGrammar.parse(body) and
      parse.respond_to?(:code)
    parse.code
  end
end

new_request() click to toggle source

# File lib/aws/s3/client.rb, line 967
def new_request
  S3::Request.new
end

populate_error(response) click to toggle source

# File lib/aws/s3/client.rb, line 941
def populate_error response
  code = response.http_response.status
  if EMPTY_BODY_ERRORS.include?(code) and
      response.http_response.body.nil?
    response.error =
      EMPTY_BODY_ERRORS[code].new(response.http_request,
                                  response.http_response)
  else
    super
  end
end

set_request_data(request, options, block) click to toggle source

# File lib/aws/s3/client.rb, line 961
def set_request_data request, options, block
  request.body_stream = data_stream_from(options, &block)
  request.headers['Content-Length'] = content_length_from(options)
end

should_retry?(response) click to toggle source

# File lib/aws/s3/client.rb, line 954
def should_retry? response
  super or
    response.request_type == :complete_multipart_upload &&
    extract_error_code(response)
end

unknown() click to toggle source

Deletes a bucket.

Required Options

:bucket_name – The name of the bucket.

# File lib/aws/s3/client.rb, line 153
bucket_method(:delete_bucket, :delete)