Class: AWS::Core::Client

Inherits:
Object
  • Object
show all
Extended by:
Naming
Defined in:
lib/aws/core/client.rb,
lib/aws/core/client/query_xml.rb,
lib/aws/core/client/query_json.rb

Overview

Base client class for all of the Amazon AWS service clients.

Defined Under Namespace

Modules: QueryJSON, QueryXML Classes: ClientRequestMethodBuilder

Constant Summary collapse

CACHEABLE_REQUESTS = 
Set[]

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Naming

service_name

Constructor Details

#initialize(options = {}) ⇒ Client

Creates a new low-level client.

Required Options

To create a client you must provide access to AWS credentials. There are two options:

  • :signer – An object that responds to access_key_id (to return the AWS Access Key ID) and to sign(string_to_sign) (to return a signature for a given string). An example implementation is AWS::Core::DefaultSigner. This option is useful if you want to more tightly control access to your secret access key (for example by moving the signature computation into a different process).

  • :access_key_id and :secret_access_key – You can use these options to provide the AWS Access Key ID and AWS Secret Access Key directly to the client.

Optional

  • :http_handler – Any object that implements a handle(request, response) method; an example is BuiltinHttpHandler. This method is used to perform the HTTP requests that this client constructs.



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/aws/core/client.rb', line 57

def initialize options = {}

  options = options.dup # so we don't modify the options passed in

  @service_ruby_name = self.class.service_ruby_name
  
  # translate these into service specific configuration options,
  # e.g. :endpoint into :s3_endpoint
  [:endpoint, :region, :port].each do |opt|
    if options[opt]
      options[:"#{service_ruby_name}_#{opt}"] = options.delete(opt)
    end
  end
  
  @config = options.delete(:config)
  @config ||= AWS.config
  @config = @config.with(options)

  @signer = @config.signer
  @http_handler = @config.http_handler
  @endpoint = config.send(:"#{service_ruby_name}_endpoint")
  @port = config.send(:"#{service_ruby_name}_port")

end

Instance Attribute Details

#config ⇒ Configuration (readonly)

Returns This clients configuration.

Returns:



83
84
85
 
# File 'lib/aws/core/client.rb', line 83

def config
  @config
end

#endpoint ⇒ String (readonly)

Returns the service endpoint (hostname) this client makes requests against.

Returns:

  • (String) —

    Returns the service endpoint (hostname) this client makes requests against.



103
104
105
 
# File 'lib/aws/core/client.rb', line 103

def endpoint
  @endpoint
end

#port ⇒ Integer (readonly)

Returns What port this client makes requests via.

Returns:

  • (Integer) —

    What port this client makes requests via.



98
99
100
 
# File 'lib/aws/core/client.rb', line 98

def port
  @port
end

#service_ruby_name ⇒ String (readonly)

Returns The snake-cased ruby name for the service (e.g. ‘s3’, ‘iam’, ‘dynamo_db’, etc).

Returns:

  • (String) —

    The snake-cased ruby name for the service (e.g. ‘s3’, ‘iam’, ‘dynamo_db’, etc).



94
95
96
 
# File 'lib/aws/core/client.rb', line 94

def service_ruby_name
  @service_ruby_name
end

#signer ⇒ DefaultSigner, Object (readonly)

Returns the signer for this client. This is normally a DefaultSigner, but it can be configured to an other object.

Returns:

  • (DefaultSigner, Object) —

    Returns the signer for this client. This is normally a DefaultSigner, but it can be configured to an other object.



89
90
91
 
# File 'lib/aws/core/client.rb', line 89

def signer
  @signer
end

Instance Method Details

#new_stub_for(method_name) ⇒ Object

Primarily used for testing, this method returns an empty psuedo service response without making a request. Its used primarily for testing the ligher level service interfaces.



160
161
162
163
164
165
166
167
 
# File 'lib/aws/core/client.rb', line 160

def new_stub_for method_name
  response = Response.new(Http::Request.new, Http::Response.new)
  response.request_type = method_name
  response.request_options = {}
  send("simulate_#{method_name}_response", response)
  response.signal_success
  response
end

#operations ⇒ Object 



106
107
108
 
# File 'lib/aws/core/client.rb', line 106

def operations
  self.class.operations
end

#stub_for(method_name) ⇒ Object

The stub returned is memoized.

See Also:



151
152
153
154
 
# File 'lib/aws/core/client.rb', line 151

def stub_for method_name
  @stubs ||= {}
  @stubs[method_name] ||= new_stub_for(method_name)
end

#with_config(config) ⇒ Core::Client

Returns a new client object with the given configuration.

Parameters:

Returns:

  • (Core::Client) —

    Returns a new client object with the given configuration.



144
145
146
 
# File 'lib/aws/core/client.rb', line 144

def with_config config
  self.class.new(:config => config)
end

#with_http_handler(handler = nil, &blk) ⇒ Core::Client

Returns a copy of the client with a different HTTP handler. You can pass an object like BuiltinHttpHandler or you can use a block; for example:

s3_with_logging = s3.with_http_handler do |request, response|
  $stderr.puts request.inspect
  super
end

The block executes in the context of an HttpHandler instance, and super delegates to the HTTP handler used by this client. This provides an easy way to spy on requests and responses. See HttpHandler, HttpRequest, and HttpResponse for more details on how to implement a fully functional HTTP handler using a different HTTP library than the one that ships with Ruby.

Parameters:

  • handler (nil) (defaults to: nil) —

    A new http handler. Leave blank and pass a block to wrap the current handler with the block.

Returns:

  • (Core::Client) —

    Returns a new instance of the client class with the modified or wrapped http handler.



130
131
132
133
 
# File 'lib/aws/core/client.rb', line 130

def with_http_handler(handler = nil, &blk)
  handler ||= Http::Handler.new(@http_handler, &blk)
  with_options(:http_handler => handler)
end

#with_options(options) ⇒ Object

Parameters:

  • options (Hash)

See Also:



137
138
139
 
# File 'lib/aws/core/client.rb', line 137

def with_options options
  with_config(config.with(options))
end