This library provides common ruby utilities to working with AWS SDK. It simplifies the work by reducing common boilerplates such as "next_token" pagination and "retry". It provides a general API Wrapper with Redis based caching, paging and retry functionalities.
AWS Dev Utilities is available from RubyGems.
Add the following to your application's Gemfile:
gem 'aws-dev-utils', '~> 1.5'And then execute:
$ bundle install
Execute the following inside your application directory:
$ gem install aws-dev-utils -v '~> 1.5'
Add the following at the top of each Ruby script, or in each module/class you want to use the with_next_token, with_cache or with_retry functions:
require 'aws-dev-utils'
using AwsDevUtils::RefinementsMany AWS operations limit the number of results returned with each response. To make it easy to get the next page of results, every AWS response object is enumerable.
This functionality is rarely needed and causes a lot of boilerplate code.
Using the client.with_next_token the paged results will be collected for you.
The AWS client function and its results will be concatenated until either no more results are available or the max number of requests is reached.
with_next_token works with APIs that use next_token, next_marker, next_continuation_token or next_record_name.
require 'aws-dev-utils'
using AwsDevUtils::Refinements
ec2_client = Aws::EC2::Client.new
# To get the full set of results:
ec2_client.
with_next_token.
describe_instances(filters:[{ name: "vpc-id", values: ["vpc-foo"]}])
# To get up to 5 pages of results:
ec2_client.
with_next_token(5).
describe_instances(filters:[{ name: "vpc-id", values: ["vpc-foo"]}])In many cases a cache is required due to many processes or different machines querying the AWS api for data.
By using the client.with_cache, the client functions results will be stored in cache.
The default cache is a simple in memory time based store - AwsDevUtils::Backend::Memory.
Incase in-memory cache is not a good solution then there is also Redis based caching (AwsDevUtils::Backend::Redis).
To use it, start a Redis instance and set it as the global cache backend:
AwsDevUtils::Cache.instance.backend = AwsDevUtils::Backend::Redis.new("redis-url")Note: Data will be restored from the cache only if it is the same request to AWS client, the same filters and the same expiration time .
# Memory Caching.
require 'aws-dev-utils'
using AwsDevUtils::Refinements
ec2_client = Aws::EC2::Client.new
ec2_client.
with_cache.
describe_instances(filters:[{ name: "vpc-id", values: ["vpc-foo"]}])# Redis based caching with default experiation time (60 seconds).
require 'aws-dev-utils'
using AwsDevUtils::Refinements
AwsDevUtils::Cache.instance.backend = AwsDevUtils::Backend::Redis.new("redis-url")
ec2_client.
with_cache.
describe_instances(filters:[{ name: "vpc-id", values: ["vpc-foo"]}])# Redis based caching with custom expiration time (10 minutes).
require 'aws-dev-utils'
using AwsDevUtils::Refinements
AwsDevUtils::Cache.instance.backend = AwsDevUtils::Backend::Redis.new("redis-url")
ec2_client.
with_cache(600).
describe_instances(filters:[{ name: "vpc-id", values: ["vpc-foo"]}])# Example of different cache keys from requests.
require 'aws-dev-utils'
using AwsDevUtils::Refinements
AwsDevUtils::Cache.instance.backend = AwsDevUtils::Backend::Redis.new("redis-url")
# No cache data so request goes to AWS servers.
foo_1_instances = ec2_client.
with_cache(600).
describe_instances(filters:[{ name: "vpc-id", values: ["vpc-foo"]}])
# Different filters than foo_1_instances so request goes to AWS servers.
bar_1_instances = ec2_client.
with_cache(600).
describe_instances(filters:[{ name: "vpc-id", values: ["vpc-bar"]}])
# Same filters as bar_1_instances, so result is fetched from cache.
bar_2_instances = ec2_client.
with_cache(600).
describe_instances(filters:[{ name: "vpc-id", values: ["vpc-bar"]}])By using the client.with_retry, the client functions will be retried in case of an exception (until the max number of retries is reached - the default is 5).
Before each retry the client will sleep for an increasing number of seconds (implements exponential backoff)
require 'aws-dev-utils'
using AwsDevUtils::Refinements
ec2_client = Aws::EC2::Client.new
# Retry 5 times (default):
ec2_client.
with_retry.
describe_instances(filters:[{ name: "vpc-id", values: ["vpc-foo"]}])
# Custom retries:
ec2_client.
with_retry(3).
describe_instances(filters:[{ name: "vpc-id", values: ["vpc-foo"]}])It is possible to combine between each of the wrappers:
require 'aws-dev-utils'
using AwsDevUtils::Refinements
ec2_client = Aws::EC2::Client.new
#To retry 5 times:
ec2_client.
with_retry.
with_next_token.
with_cache(600)
describe_instances(filters:[{ name: "vpc-id", values: ["vpc-foo"]}])The ./release-new-version.sh script will bump the version number. By default it will
increase by 0.0.1, but you can pass minor or major to increase it to the next
minor or major version accordingly.
The script will also create a git commit for the version bump, push it to this GitHub repository and upload it to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/kontera-technologies/aws-dev-utils