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