Module: AWS

Defined in:
lib/aws/core.rb,
lib/aws.rb,
lib/aws/s3.rb,
lib/aws/ec2.rb,
lib/aws/elb.rb,
lib/aws/iam.rb,
lib/aws/sns.rb,
lib/aws/sqs.rb,
lib/aws/sts.rb,
lib/aws/rails.rb,
lib/aws/errors.rb,
lib/aws/record.rb,
lib/aws/ec2/tag.rb,
lib/aws/s3/tree.rb,
lib/aws/iam/user.rb,
lib/aws/ec2/image.rb,
lib/aws/iam/group.rb,
lib/aws/s3/bucket.rb,
lib/aws/s3/client.rb,
lib/aws/s3/errors.rb,
lib/aws/s3/policy.rb,
lib/aws/simple_db.rb,
lib/aws/sns/topic.rb,
lib/aws/sqs/queue.rb,
lib/aws/core/model.rb,
lib/aws/ec2/client.rb,
lib/aws/ec2/errors.rb,
lib/aws/ec2/region.rb,
lib/aws/ec2/volume.rb,
lib/aws/elb/client.rb,
lib/aws/elb/errors.rb,
lib/aws/iam/client.rb,
lib/aws/iam/errors.rb,
lib/aws/iam/policy.rb,
lib/aws/s3/request.rb,
lib/aws/sns/client.rb,
lib/aws/sns/errors.rb,
lib/aws/sns/policy.rb,
lib/aws/sqs/client.rb,
lib/aws/sqs/errors.rb,
lib/aws/sqs/policy.rb,
lib/aws/sts/client.rb,
lib/aws/sts/errors.rb,
lib/aws/sts/policy.rb,
lib/aws/core/client.rb,
lib/aws/core/naming.rb,
lib/aws/core/policy.rb,
lib/aws/ec2/request.rb,
lib/aws/elb/request.rb,
lib/aws/iam/request.rb,
lib/aws/record/base.rb,
lib/aws/sns/request.rb,
lib/aws/sqs/request.rb,
lib/aws/sts/request.rb,
lib/aws/sts/session.rb,
lib/aws/ec2/instance.rb,
lib/aws/ec2/key_pair.rb,
lib/aws/ec2/resource.rb,
lib/aws/ec2/snapshot.rb,
lib/aws/elb/listener.rb,
lib/aws/iam/resource.rb,
lib/aws/record/scope.rb,
lib/aws/s3/s3_object.rb,
lib/aws/s3/tree/node.rb,
lib/aws/core/resource.rb,
lib/aws/core/response.rb,
lib/aws/record/errors.rb,
lib/aws/record/naming.rb,
lib/aws/record/scopes.rb,
lib/aws/s3/acl_object.rb,
lib/aws/s3/client/xml.rb,
lib/aws/core/cacheable.rb,
lib/aws/ec2/attachment.rb,
lib/aws/ec2/client/xml.rb,
lib/aws/ec2/collection.rb,
lib/aws/ec2/elastic_ip.rb,
lib/aws/elb/client/xml.rb,
lib/aws/iam/access_key.rb,
lib/aws/iam/client/xml.rb,
lib/aws/iam/collection.rb,
lib/aws/iam/mfa_device.rb,
lib/aws/s3/tree/parent.rb,
lib/aws/simple_db/item.rb,
lib/aws/sns/client/xml.rb,
lib/aws/sqs/client/xml.rb,
lib/aws/sts/client/xml.rb,
lib/aws/core/api_config.rb,
lib/aws/core/autoloader.rb,
lib/aws/core/collection.rb,
lib/aws/core/inflection.rb,
lib/aws/core/meta_utils.rb,
lib/aws/core/uri_escape.rb,
lib/aws/ec2/tagged_item.rb,
lib/aws/iam/user_policy.rb,
lib/aws/s3/data_options.rb,
lib/aws/core/page_result.rb,
lib/aws/core/xml_grammar.rb,
lib/aws/record/attribute.rb,
lib/aws/record/validator.rb,
lib/aws/s3/uploaded_part.rb,
lib/aws/simple_db/client.rb,
lib/aws/simple_db/domain.rb,
lib/aws/simple_db/errors.rb,
lib/aws/sns/subscription.rb,
lib/aws/core/async_handle.rb,
lib/aws/core/authorize_v2.rb,
lib/aws/core/authorize_v3.rb,
lib/aws/core/http/handler.rb,
lib/aws/core/http/request.rb,
lib/aws/elb/listener_opts.rb,
lib/aws/elb/load_balancer.rb,
lib/aws/iam/login_profile.rb,
lib/aws/record/conversion.rb,
lib/aws/record/exceptions.rb,
lib/aws/s3/object_version.rb,
lib/aws/s3/presigned_post.rb,
lib/aws/s3/tree/leaf_node.rb,
lib/aws/simple_db/request.rb,
lib/aws/core/configuration.rb,
lib/aws/core/http/response.rb,
lib/aws/ec2/security_group.rb,
lib/aws/ec2/tag_collection.rb,
lib/aws/record/validations.rb,
lib/aws/s3/object_metadata.rb,
lib/aws/core/client_logging.rb,
lib/aws/core/default_signer.rb,
lib/aws/core/option_grammar.rb,
lib/aws/core/resource_cache.rb,
lib/aws/core/response_cache.rb,
lib/aws/ec2/has_permissions.rb,
lib/aws/iam/user_collection.rb,
lib/aws/s3/multipart_upload.rb,
lib/aws/s3/tree/branch_node.rb,
lib/aws/simple_db/attribute.rb,
lib/aws/simple_db/item_data.rb,
lib/aws/ec2/config_transform.rb,
lib/aws/ec2/image_collection.rb,
lib/aws/iam/group_collection.rb,
lib/aws/s3/bucket_collection.rb,
lib/aws/s3/object_collection.rb,
lib/aws/simple_db/client/xml.rb,
lib/aws/simple_email_service.rb,
lib/aws/sns/topic_collection.rb,
lib/aws/sqs/queue_collection.rb,
lib/aws/sqs/received_message.rb,
lib/aws/core/indifferent_hash.rb,
lib/aws/ec2/availability_zone.rb,
lib/aws/ec2/region_collection.rb,
lib/aws/ec2/tagged_collection.rb,
lib/aws/ec2/volume_collection.rb,
lib/aws/iam/policy_collection.rb,
lib/aws/record/dirty_tracking.rb,
lib/aws/record/finder_methods.rb,
lib/aws/sts/federated_session.rb,
lib/aws/core/collection/simple.rb,
lib/aws/core/http/curb_handler.rb,
lib/aws/core/service_interface.rb,
lib/aws/ec2/reserved_instances.rb,
lib/aws/iam/server_certificate.rb,
lib/aws/s3/access_control_list.rb,
lib/aws/s3/prefixed_collection.rb,
lib/aws/core/lazy_error_classes.rb,
lib/aws/ec2/filtered_collection.rb,
lib/aws/ec2/instance_collection.rb,
lib/aws/ec2/key_pair_collection.rb,
lib/aws/ec2/snapshot_collection.rb,
lib/aws/elb/instance_collection.rb,
lib/aws/elb/listener_collection.rb,
lib/aws/iam/signing_certificate.rb,
lib/aws/record/attribute_macros.rb,
lib/aws/record/attributes/float.rb,
lib/aws/record/validators/block.rb,
lib/aws/record/validators/count.rb,
lib/aws/s3/paginated_collection.rb,
lib/aws/core/configured_grammars.rb,
lib/aws/elb/load_balancer_policy.rb,
lib/aws/record/attributes/string.rb,
lib/aws/record/validators/format.rb,
lib/aws/record/validators/length.rb,
lib/aws/record/validators/method.rb,
lib/aws/s3/tree/child_collection.rb,
lib/aws/simple_db/client/options.rb,
lib/aws/simple_db/put_attributes.rb,
lib/aws/sqs/received_sns_message.rb,
lib/aws/core/collection/batchable.rb,
lib/aws/core/collection/limitable.rb,
lib/aws/ec2/attachment_collection.rb,
lib/aws/ec2/block_device_mappings.rb,
lib/aws/ec2/elastic_ip_collection.rb,
lib/aws/ec2/permission_collection.rb,
lib/aws/iam/access_key_collection.rb,
lib/aws/iam/group_user_collection.rb,
lib/aws/iam/mfa_device_collection.rb,
lib/aws/iam/user_group_collection.rb,
lib/aws/record/attributes/boolean.rb,
lib/aws/record/attributes/integer.rb,
lib/aws/record/optimistic_locking.rb,
lib/aws/simple_db/domain_metadata.rb,
lib/aws/simple_db/item_collection.rb,
lib/aws/core/http/httparty_handler.rb,
lib/aws/core/http/net_http_handler.rb,
lib/aws/core/ignore_result_element.rb,
lib/aws/iam/user_policy_collection.rb,
lib/aws/record/attributes/datetime.rb,
lib/aws/record/validators/presence.rb,
lib/aws/ec2/resource_tag_collection.rb,
lib/aws/iam/group_policy_collection.rb,
lib/aws/record/validators/exclusion.rb,
lib/aws/record/validators/inclusion.rb,
lib/aws/s3/object_upload_collection.rb,
lib/aws/s3/uploaded_part_collection.rb,
lib/aws/simple_db/delete_attributes.rb,
lib/aws/simple_db/domain_collection.rb,
lib/aws/simple_email_service/client.rb,
lib/aws/simple_email_service/errors.rb,
lib/aws/simple_email_service/quotas.rb,
lib/aws/sns/subscription_collection.rb,
lib/aws/core/configured_xml_grammars.rb,
lib/aws/elb/load_balancer_collection.rb,
lib/aws/iam/account_alias_collection.rb,
lib/aws/record/validators/acceptance.rb,
lib/aws/s3/bucket_version_collection.rb,
lib/aws/s3/object_version_collection.rb,
lib/aws/simple_email_service/request.rb,
lib/aws/ec2/security_group_collection.rb,
lib/aws/core/configured_client_methods.rb,
lib/aws/record/validators/confirmation.rb,
lib/aws/record/validators/numericality.rb,
lib/aws/s3/multipart_upload_collection.rb,
lib/aws/simple_db/attribute_collection.rb,
lib/aws/core/configured_option_grammars.rb,
lib/aws/ec2/reserved_instances_offering.rb,
lib/aws/simple_email_service/client/xml.rb,
lib/aws/ec2/availability_zone_collection.rb,
lib/aws/ec2/security_group/ip_permission.rb,
lib/aws/elb/availability_zone_collection.rb,
lib/aws/record/attributes/sortable_float.rb,
lib/aws/simple_db/consistent_read_option.rb,
lib/aws/core/authorize_with_session_token.rb,
lib/aws/ec2/reserved_instances_collection.rb,
lib/aws/iam/server_certificate_collection.rb,
lib/aws/simple_db/expect_condition_option.rb,
lib/aws/sns/topic_subscription_collection.rb,
lib/aws/iam/signing_certificate_collection.rb,
lib/aws/record/attributes/sortable_integer.rb,
lib/aws/s3/prefix_and_delimiter_collection.rb,
lib/aws/elb/load_balancer_policy_collection.rb,
lib/aws/elb/backend_server_policy_collection.rb,
lib/aws/ec2/reserved_instances_offering_collection.rb,
lib/aws/simple_email_service/email_address_collection.rb,
lib/aws/ec2/security_group/egress_ip_permission_collection.rb,
lib/aws/ec2/security_group/ingress_ip_permission_collection.rb

Overview

Copyright 2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the “License”). You may not use this file except in compliance with the License. A copy of the License is located at

http://aws.amazon.com/apache2.0/

or in the “license” file accompanying this file. This file is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Defined Under Namespace

Modules: Core, Errors, Rails, Record Classes: EC2, ELB, IAM, S3, SNS, SQS, STS, SimpleDB, SimpleEmailService

Constant Summary collapse

VERSION =

Current version of the AWS SDK for Ruby

"1.2.0"
@@eager = 
false
@@autoloads = 
{}

Class Method Summary collapse

Class Method Details

.add_service(name, ruby_name, default_endpoint) ⇒ Object 



381
382
383
384
385
386
387
388
389
390
391
392
393
394
 
# File 'lib/aws/core.rb', line 381

def add_service name, ruby_name, default_endpoint

  create_block = lambda do |config| 
    AWS.const_get(name)::Client.new(:config => config)
  end

  needs = [:signer, :http_handler, :"#{ruby_name}_endpoint"]

  Core::Configuraiton.add_option :"#{ruby_name}_endpoint", default_endpoint

  Core::Configuraiton.add_option_with_needs(
    :"#{ruby_name}_client", needs, &create_block)

end

.autoloads ⇒ Object 



37
38
39
 
# File 'lib/aws/core/autoloader.rb', line 37

def self.autoloads
  @@autoloads
end

.config(options = {}) ⇒ Core::Configuration

Note:

Changing the global configuration does not affect objects that have already been constructed.

The global configuration for AWS. Generally you set your prefered configuration operations once after loading the aws-sdk gem.

AWS.config({
  :access_key_id => 'ACCESS_KEY_ID',
  :secret_access_key => 'SECRET_ACCESS_KEY',
  :simple_db_endpoint => 'sdb.us-west-1.amazonaws.com',
  :max_retries => 2,
})

When using AWS classes they will always default to use configuration values defined in config.

AWS.config(:max_retries => 2)

sqs = AWS::SQS.new
sqs.config.max_retries #=> 2

If you want to change a configuration value for a single instance you pass the new configuration value to that object’s initializer:

AWS::SQS.new(:max_retries => 0)

Parameters:

  • options (Hash) (defaults to: {})
  • options[Boolean] (Hash) —

    a customizable set of options

Options Hash (options):

  • :access_key_id (String) — default: nil —

    AWS access key id credential.

  • :ec2_endpoint (String) — default: 'ec2.amazonaws.com' —

    The service endpoint for Amazon EC2.

  • :http_handler (Object) — default: AWS::HTTPartyHandler —

    The http handler that sends requests to AWS.

  • :iam_endpoint (String) — default: 'iam.amazonaws.com' —

    The service endpoint for AWS Idenity Access Management (IAM).

  • :logger (Object, nil) — default: nil —

    A logger instance that should receive log messages generated by service requets.

    A logger needs to respond to #log and must accept a severity (e.g. :info, :error, etc) and a string message.

  • :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')
  • :s3_endpoint (String) — default: 's3.amazonaws.com' —

    The service endpoint for Amazon S3.

  • :s3_multipart_max_parts (Integer) — default: 1000 —

    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 exceedes :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:

  • :secret_access_key (String) — default: nil —

    AWS secret access key credential.

  • :session_token (String, nil) — default: nil —

    AWS secret token credential.

  • :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.

  • :signer (Object) — default: AWS::DefaultSigner —

    The request signer. Defaults to a default request signer implementation.

  • :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_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.

  • :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.

  • :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 requets against AWS services. This should be set for clients and applications built ontop of the aws-sdk gem.

Returns:



262
263
264
265
266
 
# File 'lib/aws/core.rb', line 262

def config options = {}
  @@config ||= Core::Configuration.new
  @@config = @@config.with(options) unless options.empty?
  @@config
end

.eager_autoload! ⇒ Object 



30
31
32
33
34
35
 
# File 'lib/aws/core/autoloader.rb', line 30

def self.eager_autoload!
  unless @@eager
    @@eager = true
    @@autoloads.values.uniq.each {|file_path| require(file_path) }
  end
end

.memoize ⇒ Object

Note:

Memoization is currently only supported for the EC2 APIs; other APIs are unaffected by the status of memoization. To protect your code from future changes in memoization support, you should not enable memoization while calling non-EC2 APIs.

Enables memoization for the current thread, within a block. Memoization lets you avoid making multiple requests for the same data by reusing the responses which have already been received. For example, consider the following code to get the most recently launched EC2 instance:

latest = ec2.instances.sort_by(&:launch_time).last

The above code would make N+1 requests (where N is the number of instances in the account); iterating the collection of instances is one request, and Enumerable#sort_by calls AWS::EC2::Instance#launch_time for each instance, causing another request per instance. We can rewrite the code as follows to make only one request:

latest = AWS.memoize do
  ec2.instances.sort_by(&:launch_time).last
end

Iterating the collection still causes a request, but each subsequent call to AWS::EC2::Instance#launch_time uses the results from that first request rather than making a new request for the same data.

While memoization is enabled, every response that is received from the service is retained in memory. Therefore you should use memoization only for short-lived blocks of code that make relatively small numbers of requests. The cached responses are used in two ways while memoization is enabled:

  1. Before making a request, the SDK checks the cache for a response to a request with the same signature (credentials, service endpoint, operation name, and parameters). If such a response is found, it is used instead of making a new request.

  2. Before retrieving data for an attribute of a resource (e.g. AWS::EC2::Instance#launch_time), the SDK attempts to find a cached response that contains the requested data. If such a response is found, the cached data is returned instead of making a new request.

When memoization is disabled, all previously cached responses are discarded.



354
355
356
357
358
359
360
361
362
363
 
# File 'lib/aws/core.rb', line 354

def memoize
  return yield if memoizing?

  begin
    start_memoizing
    yield if block_given?
  ensure
    stop_memoizing
  end
end

.memoizing? ⇒ Boolean

Note:

Memoization is currently only supported for the EC2 APIs; other APIs are unaffected by the status of memoization. To protect your code from future changes in memoization support, you should not enable memoization while calling non-EC2 APIs.

Returns True if memoization is enabled for the current thread. See memoize for a full discussion of the memoization feature.

Returns:

  • (Boolean) —

    True if memoization is enabled for the current thread. See memoize for a full discussion of the memoization feature.



301
302
303
 
# File 'lib/aws/core.rb', line 301

def memoizing?
  !Thread.current[:aws_memoization].nil?
end

.register_autoloads(klass, prefix = nil, &block) ⇒ Object 



21
22
23
24
25
26
27
28
 
# File 'lib/aws/core/autoloader.rb', line 21

def self.register_autoloads klass, prefix = nil, &block
  autoloader = Core::Autoloader.new(klass, prefix)
  autoloader.instance_eval(&block)
  autoloader.autoloads.each_pair do |const_name, file_path|
    require(file_path) if @@eager
    @@autoloads["#{klass}::#{const_name}"] = file_path
  end
end

.start_memoizing ⇒ Object

Note:

Memoization is currently only supported for the EC2 APIs; other APIs are unaffected by the status of memoization. To protect your code from future changes in memoization support, you should not enable memoization while calling non-EC2 APIs.

Starts memoizing service requests made in the current thread. See memoize for a full discussion of the memoization feature. This has no effect if memoization is already enabled.



276
277
278
279
 
# File 'lib/aws/core.rb', line 276

def start_memoizing
  Thread.current[:aws_memoization] ||= {}
  nil
end

.stop_memoizing ⇒ Object

Note:

Memoization is currently only supported for the EC2 APIs; other APIs are unaffected by the status of memoization. To protect your code from future changes in memoization support, you should not enable memoization while calling non-EC2 APIs.

Stops memoizing service requests made in the current thread. See memoize for a full discussion of the memoization feature. This has no effect if memoization is already disabled.



289
290
291
 
# File 'lib/aws/core.rb', line 289

def stop_memoizing
  Thread.current[:aws_memoization] = nil
end

.stub! ⇒ nil

Causes all requests to return empty responses without making any requests against the live services. This does not attempt to mock the services.

Returns:

  • (nil) 


400
401
402
403
 
# File 'lib/aws/core.rb', line 400

def stub!
  config(:stub_requests => true)
  nil
end