Class: AWS::Core::Client

Inherits:

Object

Object
AWS::Core::Client

show all

Defined in:: lib/aws/core/client.rb

Overview

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

Direct Known Subclasses

JSONClient, QueryClient, RESTJSONClient, RESTXMLClient, S3::Client

Defined Under Namespace

Classes: NetworkError

Instance Attribute Summary collapse

#config ⇒ Configuration readonly

This clients configuration.
#http_read_timeout ⇒ Integer readonly

The number of seconds before requests made by this client should timeout if they have not received a response.

Class Method Summary collapse

.operations ⇒ Array<Symbol>

Returns a list of service operations as method names supported by this client.

Instance Method Summary collapse

#initialize(options = {}) ⇒ Client constructor

Creates a new low-level client.
#log_warning(warning) ⇒ nil

Logs the warning to the configured logger, otherwise to stderr.
#operations ⇒ Object
#with_http_handler(handler = nil, &blk) ⇒ Core::Client

Returns a copy of the client with a different HTTP handler.
#with_options(options) ⇒ Client

Returns a new client with the passed configuration options merged with the current configuration options.

Constructor Details

#initialize(options = {}) ⇒ `Client`

Creates a new low-level client.

Parameters:

options (Hash) (defaults to: {})

Options Hash (options):

:config (Core::Configuration) — default: AWS.config —

The base configuration object to use. All other options are merged with this. Defaults to the AWS.config.
:access_key_id (String) —

AWS access key id credential.
:secret_access_key (String) —

AWS secret access key credential.
:session_token (String, nil) —

AWS secret token credential.
:auto_scaling_endpoint (String) — default: 'autoscaling.us-east-1.amazonaws.com' —

The service endpoint for Auto Scaling.
:cloud_formation_endpoint (String) — default: 'cloudformation.us-east-1.amazonaws.com' —

The service endpoint for AWS CloudFormation.
:cloud_front_endpoint (String) — default: 'cloudfront.amazonaws.com' —

The service endpoint for Amazon CloudFront.
:cloud_search (String) — default: 'cloudsearch.us-east-1.amazonaws.com' —

The service endpoint for Amazon CloudSearch.
:cloud_watch_endpoint (String) — default: 'monitoring.us-east-1.amazonaws.com' —

The service endpoint for Amazon CloudWatch.
:dynamo_db_big_decimals (Boolean) — default: true —

When true, DynamoDB will convert number values returned by DynamoDB::Client from strings to BigDecimal objects. If you set this to false, they will be converted from strings into floats (with a potential loss of precision).
:dynamo_db_endpoint (String) — default: 'dynamodb.amazonaws.com' —

The service endpoint for Amazon DynamoDB.
:dynamo_db_retry_throughput_errors (Boolean) — default: true —

When true, AWS::DynamoDB::Errors::ProvisionedThroughputExceededException errors will be retried.
:ec2_endpoint (String) — default: 'ec2.amazonaws.com' —

The service endpoint for Amazon EC2.
:elasticache_endpoint (String) — default: 'elasticache.us-east-1.amazonaws.com'
:elastic_beanstalk_endpoint (String) — default: 'elasticbeanstalk.us-east-1.amazonaws.com' —

The service endpoint for AWS Elastic Beanstalk.
:elastic_transcoder_endpoint (String) — default: 'elastictranscoder.us-east-1.amazonaws.com' —

The service endpoint for Elastic Transcoder.
:elb_endpoint (String) — default: 'elasticloadbalancing.us-east-1.amazonaws.com' —

The service endpoint for Elastic Load Balancing.
:glacier_endpoint (String) — default: 'glacier.us-east-1.amazonaws.com' —

The service endpoint for Amazon Glacier.
:http_handler (Object) — default: AWS::Core::Http::NetHttpHandler —

The http handler that sends requests to AWS.
:http_idle_timeout (Integer) — default: 60 —

The number of seconds a persistent connection is allowed to sit idle before it should no longer be used.
:http_open_timeout (Integer) — default: 15 —

The number of seconds before the :http_handler should timeout while trying to open a new HTTP session.
:http_read_timeout (Integer) — default: 60 —

The number of seconds before the :http_handler should timeout while waiting for a HTTP response.
:http_wire_trace (Boolean) — default: false —

When true, the http handler will log all wire traces to the :logger. If a :logger is not configured, then wire traces will be sent to standard out.
:iam_endpoint (String) — default: 'iam.amazonaws.com' —

The service endpoint for AWS Identity Access Management (IAM).
:import_export_endpoint (String) — default: 'importexport.amazonaws.com' —

The service endpoint for AWS Import/Export.
:logger (Logger, nil) — default: nil —
A logger to send log messages to. Here is an example that logs to standard out.
```
require 'logger'
AWS.config(:logger => Logger.new($stdout))
```
:log_level (Symbol) — default: :info —

The level log messages are sent to the logger with (e.g. :notice, :info, :warn, :debug, etc).
:log_formatter (Object) —
The log formatter is responsible for building log messages from responses. You can quickly change log formats by providing a pre-configured log formatter.
```
AWS.config(:log_formatter => AWS::Core::LogFormatter.colored)
```
Here is a list of pre-configured log formatters:
- AWS::Core::LogFormatter.default
- AWS::Core::LogFormatter.short
- AWS::Core::LogFormatter.debug
- AWS::Core::LogFormatter.colored
You can also create an instance of AWS::Core::LogFormatter with a custom log message pattern. See LogFormatter for a complete list of pattern substitutions.
```
pattern = "[AWS :operation :duration] :error_message"
AWS.config(:log_formatter => AWS::Core::LogFormatter.new(pattern))
```
Lastly you can pass any object that responds to #format accepting and instance of Response and returns a string.
:max_retries (Integer) — default: 3 —

The maximum number of times service errors (500) should be retried. There is an exponential backoff in between service request retries, so the more retries the longer it can take to fail.
:proxy_uri (String, URI, nil) — default: nil —
The URI of the proxy to send service requests through. You can pass a URI object or a URI string:
```
AWS.config(:proxy_uri => 'https://user:[email protected]:443/path?query')
```
:ops_works_endpoint (String) — default: 'opsworks.us-east-1.amazonaws.com' —

The service endpoint for AWS OpsWorks.
:redshift_endpoint (String) — default: 'redshift.us-east-1.amazonaws.com' —

The service endpoint for Amazon Redshift.
:rds_endpoint (String) — default: 'rds.us-east-1.amazonaws.com' —

The service endpoint for Amazon Relational Database Service (RDS).
:route_53_endpoint (String) — default: 'route53.amazonaws.com' —

The service endpoint for Amazon Route 53.
:s3_endpoint (String) — default: 's3.amazonaws.com' —

The service endpoint for Amazon S3.
:s3_force_path_style (Boolean) — default: false —

When true, requests will always use path style. This can be useful for testing environments.
:s3_multipart_max_parts (Integer) — default: 10000 —

The maximum number of parts to split a file into when uploading in parts to S3.
:s3_multipart_threshold (Integer) — default: 16777216 —

When uploading data to S3, if the number of bytes to send exceeds :s3_multipart_threshold then a multi part session is automatically started and the data is sent up in chunks. The size of each part is specified by :s3_multipart_min_part_size. Defaults to 16777216 (16MB).
:s3_multipart_min_part_size (Integer) — default: 5242880 —

The absolute minimum size (in bytes) each S3 multipart segment should be. Defaults to 5242880 (5MB).
:s3_server_side_encryption (Symbol) — default: nil —
The algorithm to use when encrypting object data on the server side. The only valid value is :aes256, which specifies that the object should be stored using the AES encryption algorithm with 256 bit keys. Defaults to nil, meaning server side encryption is not used unless specified on each individual call to upload an object. This option controls the default behavior for the following methods:
:s3_encryption_key (OpenSSL::PKey::RSA, String) — default: nil —

If this is set, AWS::S3::S3Object #read and #write methods will always perform client-side encryption with this key. The key can be overridden at runtime by using the :encryption_key option. A value of nil means that client-side encryption will not be used.
:s3_encryption_materials_location (Symbol) — default: :metadata —

When set to :instruction_file, AWS::S3::S3Object will store encryption materials in a separate object, instead of the object metadata.
:simple_db_endpoint (String) — default: 'sdb.amazonaws.com' —

The service endpoint for Amazon SimpleDB.
:simple_db_consistent_reads (Boolean) — default: false —

Determines if all SimpleDB read requests should be done consistently. Consistent reads are slower, but reflect all changes to SDB.
:simple_email_service_endpoint (String) — default: 'email.us-east-1.amazonaws.com' —

The service endpoint for Amazon Simple Email Service.
:simple_workflow_endpoint (String) — default: 'swf.us-east-1.amazonaws.com' —

The service endpoint for Amazon Simple Workflow Service.
:credential_provider (CredentialProviders::Provider) — default: AWS::Core::CredentialProviders::DefaultProvider.new —

Returns the credential provider. The default credential provider attempts to check for statically assigned credentials, ENV credentials and credentials in the metadata service of EC2.
:ssl_ca_file (String) —

The path to a CA cert bundle in PEM format.

If :ssl_verify_peer is true (the default) this bundle will be used to validate the server certificate in each HTTPS request. The AWS SDK for Ruby ships with a CA cert bundle, which is the default value for this option.
:ssl_ca_path (String) — default: nil —

The path the a CA cert directory.
:ssl_verify_peer (Boolean) — default: true —

When true the HTTP handler validate server certificates for HTTPS requests.

This option should only be disabled for diagnostic purposes; leaving this option set to false exposes your application to man-in-the-middle attacks and can pose a serious security risk.
:stub_requests (Boolean) — default: false —

When true requests are not sent to AWS, instead empty responses are generated and returned to each service request.
:sns_endpoint (String) — default: 'sns.us-east-1.amazonaws.com' —

The service endpoint for Amazon SNS.
:sqs_endpoint (String) — default: 'sqs.us-east-1.amazonaws.com' —

The service endpoint for Amazon SQS.
:storage_gateway_endpoint (String) — default: 'storagegateway.us-east-1.amazonaws.com' —

The service endpoint for AWS Storage Gateway.
:sts_endpoint (String) — default: 'sts.amazonaws.com' —

The service endpoint for AWS Security Token Service.
:use_ssl (Boolean) — default: true —

When true, all requests to AWS are sent using HTTPS instead vanilla HTTP.
:user_agent_prefix (String) — default: nil —

A string prefix to append to all requests against AWS services. This should be set for clients and applications built ontop of the aws-sdk gem.

# File 'lib/aws/core/client.rb', line 41

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) || AWS.config)
  @config = @config.with(options)

  @credential_provider = @config.credential_provider
  @http_handler = @config.http_handler
  @endpoint = config.send(:"#{service_ruby_name}_endpoint")
  @port = config.send(:"#{service_ruby_name}_port")
  if config.send(:"#{service_ruby_name}_service_path") <=> "/"
    @uri = config.send(:"#{service_ruby_name}_service_path")
  end 
  @http_read_timeout = @config.http_read_timeout

end

Instance Attribute Details

#config ⇒ `Configuration` (readonly)

Returns This clients configuration.

Returns:

(Configuration) —

This clients configuration.



70
71
72

# File 'lib/aws/core/client.rb', line 70

def config
  @config
end

#http_read_timeout ⇒ `Integer` (readonly)

Returns The number of seconds before requests made by this client should timeout if they have not received a response.

Returns:

(Integer) —

The number of seconds before requests made by this client should timeout if they have not received a response.



88
89
90

# File 'lib/aws/core/client.rb', line 88

def http_read_timeout
  @http_read_timeout
end

Class Method Details

.operations ⇒ `Array<Symbol>`

Returns a list of service operations as method names supported by this client.

Returns:

(Array<Symbol>) —

Returns a list of service operations as method names supported by this client.



557
558
559

# File 'lib/aws/core/client.rb', line 557

def operations
  @operations ||= []
end

Instance Method Details

#log_warning(warning) ⇒ `nil`

Logs the warning to the configured logger, otherwise to stderr.

Parameters:

warning (String)

Returns:

(nil)

# File 'lib/aws/core/client.rb', line 175

def log_warning warning
  message = '[aws-sdk-gem-warning] ' + warning
  if config.logger
    config.logger.warn(message)
  else
    $stderr.puts(message)
  end
  nil
end

#operations ⇒ `Object`



101
102
103

# File 'lib/aws/core/client.rb', line 101

def operations
  self.class.operations
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(request, response)
  $stderr.puts response.inspect
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.

# File 'lib/aws/core/client.rb', line 126

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

#with_options(options) ⇒ `Client`

Returns a new client with the passed configuration options merged with the current configuration options.

no_retry_client = client.with_options(:max_retries => 0)

Parameters:

options (Hash)

Options Hash (options):

:access_key_id (String) —

AWS access key id credential.
:secret_access_key (String) —

AWS secret access key credential.
:session_token (String, nil) —

AWS secret token credential.
:auto_scaling_endpoint (String) — default: 'autoscaling.us-east-1.amazonaws.com' —

The service endpoint for Auto Scaling.
:cloud_formation_endpoint (String) — default: 'cloudformation.us-east-1.amazonaws.com' —

The service endpoint for AWS CloudFormation.
:cloud_front_endpoint (String) — default: 'cloudfront.amazonaws.com' —

The service endpoint for Amazon CloudFront.
:cloud_search (String) — default: 'cloudsearch.us-east-1.amazonaws.com' —

The service endpoint for Amazon CloudSearch.
:cloud_watch_endpoint (String) — default: 'monitoring.us-east-1.amazonaws.com' —

The service endpoint for Amazon CloudWatch.
:dynamo_db_big_decimals (Boolean) — default: true —

When true, DynamoDB will convert number values returned by DynamoDB::Client from strings to BigDecimal objects. If you set this to false, they will be converted from strings into floats (with a potential loss of precision).
:dynamo_db_endpoint (String) — default: 'dynamodb.amazonaws.com' —

The service endpoint for Amazon DynamoDB.
:dynamo_db_retry_throughput_errors (Boolean) — default: true —

When true, AWS::DynamoDB::Errors::ProvisionedThroughputExceededException errors will be retried.
:ec2_endpoint (String) — default: 'ec2.amazonaws.com' —

The service endpoint for Amazon EC2.
:elasticache_endpoint (String) — default: 'elasticache.us-east-1.amazonaws.com'
:elastic_beanstalk_endpoint (String) — default: 'elasticbeanstalk.us-east-1.amazonaws.com' —

The service endpoint for AWS Elastic Beanstalk.
:elastic_transcoder_endpoint (String) — default: 'elastictranscoder.us-east-1.amazonaws.com' —

The service endpoint for Elastic Transcoder.
:elb_endpoint (String) — default: 'elasticloadbalancing.us-east-1.amazonaws.com' —

The service endpoint for Elastic Load Balancing.
:glacier_endpoint (String) — default: 'glacier.us-east-1.amazonaws.com' —

The service endpoint for Amazon Glacier.
:http_handler (Object) — default: AWS::Core::Http::NetHttpHandler —

The http handler that sends requests to AWS.
:http_idle_timeout (Integer) — default: 60 —

The number of seconds a persistent connection is allowed to sit idle before it should no longer be used.
:http_open_timeout (Integer) — default: 15 —

The number of seconds before the :http_handler should timeout while trying to open a new HTTP session.
:http_read_timeout (Integer) — default: 60 —

The number of seconds before the :http_handler should timeout while waiting for a HTTP response.
:http_wire_trace (Boolean) — default: false —

When true, the http handler will log all wire traces to the :logger. If a :logger is not configured, then wire traces will be sent to standard out.
:iam_endpoint (String) — default: 'iam.amazonaws.com' —

The service endpoint for AWS Identity Access Management (IAM).
:import_export_endpoint (String) — default: 'importexport.amazonaws.com' —

The service endpoint for AWS Import/Export.
:logger (Logger, nil) — default: nil —
A logger to send log messages to. Here is an example that logs to standard out.
```
require 'logger'
AWS.config(:logger => Logger.new($stdout))
```
:log_level (Symbol) — default: :info —

The level log messages are sent to the logger with (e.g. :notice, :info, :warn, :debug, etc).
:log_formatter (Object) —
The log formatter is responsible for building log messages from responses. You can quickly change log formats by providing a pre-configured log formatter.
```
AWS.config(:log_formatter => AWS::Core::LogFormatter.colored)
```
Here is a list of pre-configured log formatters:
- AWS::Core::LogFormatter.default
- AWS::Core::LogFormatter.short
- AWS::Core::LogFormatter.debug
- AWS::Core::LogFormatter.colored
You can also create an instance of AWS::Core::LogFormatter with a custom log message pattern. See LogFormatter for a complete list of pattern substitutions.
```
pattern = "[AWS :operation :duration] :error_message"
AWS.config(:log_formatter => AWS::Core::LogFormatter.new(pattern))
```
Lastly you can pass any object that responds to #format accepting and instance of Response and returns a string.
:max_retries (Integer) — default: 3 —

The maximum number of times service errors (500) should be retried. There is an exponential backoff in between service request retries, so the more retries the longer it can take to fail.
:proxy_uri (String, URI, nil) — default: nil —
The URI of the proxy to send service requests through. You can pass a URI object or a URI string:
```
AWS.config(:proxy_uri => 'https://user:[email protected]:443/path?query')
```
:ops_works_endpoint (String) — default: 'opsworks.us-east-1.amazonaws.com' —

The service endpoint for AWS OpsWorks.
:redshift_endpoint (String) — default: 'redshift.us-east-1.amazonaws.com' —

The service endpoint for Amazon Redshift.
:rds_endpoint (String) — default: 'rds.us-east-1.amazonaws.com' —

The service endpoint for Amazon Relational Database Service (RDS).
:route_53_endpoint (String) — default: 'route53.amazonaws.com' —

The service endpoint for Amazon Route 53.
:s3_endpoint (String) — default: 's3.amazonaws.com' —

The service endpoint for Amazon S3.
:s3_force_path_style (Boolean) — default: false —

When true, requests will always use path style. This can be useful for testing environments.
:s3_multipart_max_parts (Integer) — default: 10000 —

The maximum number of parts to split a file into when uploading in parts to S3.
:s3_multipart_threshold (Integer) — default: 16777216 —

When uploading data to S3, if the number of bytes to send exceeds :s3_multipart_threshold then a multi part session is automatically started and the data is sent up in chunks. The size of each part is specified by :s3_multipart_min_part_size. Defaults to 16777216 (16MB).
:s3_multipart_min_part_size (Integer) — default: 5242880 —

The absolute minimum size (in bytes) each S3 multipart segment should be. Defaults to 5242880 (5MB).
:s3_server_side_encryption (Symbol) — default: nil —
The algorithm to use when encrypting object data on the server side. The only valid value is :aes256, which specifies that the object should be stored using the AES encryption algorithm with 256 bit keys. Defaults to nil, meaning server side encryption is not used unless specified on each individual call to upload an object. This option controls the default behavior for the following methods:
:s3_encryption_key (OpenSSL::PKey::RSA, String) — default: nil —

If this is set, AWS::S3::S3Object #read and #write methods will always perform client-side encryption with this key. The key can be overridden at runtime by using the :encryption_key option. A value of nil means that client-side encryption will not be used.
:s3_encryption_materials_location (Symbol) — default: :metadata —

When set to :instruction_file, AWS::S3::S3Object will store encryption materials in a separate object, instead of the object metadata.
:simple_db_endpoint (String) — default: 'sdb.amazonaws.com' —

The service endpoint for Amazon SimpleDB.
:simple_db_consistent_reads (Boolean) — default: false —

Determines if all SimpleDB read requests should be done consistently. Consistent reads are slower, but reflect all changes to SDB.
:simple_email_service_endpoint (String) — default: 'email.us-east-1.amazonaws.com' —

The service endpoint for Amazon Simple Email Service.
:simple_workflow_endpoint (String) — default: 'swf.us-east-1.amazonaws.com' —

The service endpoint for Amazon Simple Workflow Service.
:credential_provider (CredentialProviders::Provider) — default: AWS::Core::CredentialProviders::DefaultProvider.new —

Returns the credential provider. The default credential provider attempts to check for statically assigned credentials, ENV credentials and credentials in the metadata service of EC2.
:ssl_ca_file (String) —

The path to a CA cert bundle in PEM format.

If :ssl_verify_peer is true (the default) this bundle will be used to validate the server certificate in each HTTPS request. The AWS SDK for Ruby ships with a CA cert bundle, which is the default value for this option.
:ssl_ca_path (String) — default: nil —

The path the a CA cert directory.
:ssl_verify_peer (Boolean) — default: true —

When true the HTTP handler validate server certificates for HTTPS requests.

This option should only be disabled for diagnostic purposes; leaving this option set to false exposes your application to man-in-the-middle attacks and can pose a serious security risk.
:stub_requests (Boolean) — default: false —

When true requests are not sent to AWS, instead empty responses are generated and returned to each service request.
:sns_endpoint (String) — default: 'sns.us-east-1.amazonaws.com' —

The service endpoint for Amazon SNS.
:sqs_endpoint (String) — default: 'sqs.us-east-1.amazonaws.com' —

The service endpoint for Amazon SQS.
:storage_gateway_endpoint (String) — default: 'storagegateway.us-east-1.amazonaws.com' —

The service endpoint for AWS Storage Gateway.
:sts_endpoint (String) — default: 'sts.amazonaws.com' —

The service endpoint for AWS Security Token Service.
:use_ssl (Boolean) — default: true —

When true, all requests to AWS are sent using HTTPS instead vanilla HTTP.
:user_agent_prefix (String) — default: nil —

A string prefix to append to all requests against AWS services. This should be set for clients and applications built ontop of the aws-sdk gem.

Returns:

(Client)



139
140
141

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

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

Class: AWS::Core::Client

Overview

Direct Known Subclasses

Defined Under Namespace

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

Instance Attribute Details

#config ⇒ Configuration (readonly)

#http_read_timeout ⇒ Integer (readonly)

Class Method Details

.operations ⇒ Array<Symbol>

Instance Method Details

#log_warning(warning) ⇒ nil

#operations ⇒ Object

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

#with_options(options) ⇒ Client

#initialize(options = {}) ⇒ `Client`

#config ⇒ `Configuration` (readonly)

#http_read_timeout ⇒ `Integer` (readonly)

.operations ⇒ `Array<Symbol>`

#log_warning(warning) ⇒ `nil`

#operations ⇒ `Object`

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

#with_options(options) ⇒ `Client`