aws-dev-utils 1.4.4 → 1.4.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34a8659230582635341c256080cf9799b0a61a1e0b310234f8d86a695460cbba
-  data.tar.gz: 540c636ebcb5c10668575ed17ce64832e9e88932582a89250f85f87db6965900
+  metadata.gz: 4687e761d49ec6e0b5c4c49e8a0eb2bbca0505940b309c5b62eb2b82413645d6
+  data.tar.gz: 6916a3900eba9cef3409f86a0ec7eb0984eb0b631c18a1b18f617ad49070c6f9
 SHA512:
-  metadata.gz: 8dcd8e2f81e666beed0e3e96cdaea536024f2acd9f6b839bf9086e42b175af4d9e4d2c997484eb4c2c20d5f763d43bac871159fd046c0b071836924b767e7ad1
-  data.tar.gz: 9ec27b077aa93bba943e5d188fb8fab8ecf80dc2b9e7ff8bff226da57496c379d20b8ee4c6961f869b0f690a6017ca6327d8bbc35aca27a83f8ad41f392b1224
+  metadata.gz: 472cbb329917024f484fc736d7226b5e4e6207ec3d9223e4df1d9c5a619a882f7dfcbc612a26e87a689ad3b781a75bfb36bc47410bf88a84b4381be9317a0a7d
+  data.tar.gz: d2403e51af30fb2c4205305fbe8c258b03bbcb1cd080ffa726f20ffa6006ac9b0ff731af0f3a991f0cf8c5da93f3d95c5e9c402db25051d4a7e075f240edc4d5

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Amobee BI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,166 @@
+# AWS Dev Utilities [![Build Status](https://travis-ci.org/kontera-technologies/aws-dev-utils.svg?branch=master)](https://travis-ci.org/kontera-technologies/aws-dev-utils) [![codecov](https://codecov.io/gh/kontera-technologies/aws-dev-utils/branch/master/graph/badge.svg)](https://codecov.io/gh/kontera-technologies/aws-dev-utils)
+
+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.
+
+## Installation
+AWS Dev Utilities is available from RubyGems.  
+
+### Option 1: Via Bundler
+Add the following to your application's Gemfile:
+```ruby
+gem 'aws-dev-utils', '~> 1.4'
+```
+And then execute:
+```
+$ bundle install
+```
+### Option 2: Via `gem install`
+Execute the following inside your application directory:
+```
+$ gem install aws-dev-utils -v '~> 1.4'
+```
+## Usage
+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:
+```ruby
+require 'aws-dev-utils'
+using AwsDevUtils::Refinements
+```
+
+### with_next_token
+Many 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` or `next_continuation_token`._
+
+```ruby
+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"]}])
+```
+
+### with_cache
+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:
+```ruby
+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 ._
+
+```ruby
+# 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"]}])
+```
+
+```ruby
+# 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"]}])
+```
+
+```ruby
+# 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"]}])
+```
+
+```ruby
+# 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"]}])
+```
+
+### with_retry
+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)
+```ruby
+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"]}])
+```
+
+### Combinations of wrappers
+It is possible to combine between each of the wrappers:
+```ruby
+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"]}])
+```
+
+## Contributing
+
+### Releasing a new version
+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](https://rubygems.org).
+
+### Bugs and PRs
+Bug reports and pull requests are welcome on GitHub at https://github.com/kontera-technologies/aws-dev-utils

data/lib/aws-dev-utils/backends/memory.rb

@@ -6,11 +6,16 @@ module AwsDevUtils
         @hash = {}
       end
 
+      # Get the value of key, if not found, returns nil.
       def get key
         clean_cache!
         @hash[key][1]
       end
 
+      # Set key to hold the value and set key to timeout after the a given expiration time(in seconds).
+      # @param key [Object]
+      # @param value [Object]
+      # @param exp [Integer]  - the key-value timeout
       def set key, value, exp
         clean_cache!
         @hash[key] = [Time.now + exp, value]

data/lib/aws-dev-utils/backends/redis.rb

@@ -4,13 +4,13 @@ module AwsDevUtils
   module Backend
     class Redis
       # :nocov:
-      # Initialize a new redis client
-      # @param [String] url - specify redis url connection
+      # Initialize a new redis client.
+      # @params url [String] - specify redis url connection
       def initialize url='redis://localhost:6379'
         @redis = ::Redis.new(url: url)
       end
 
-      # Get the value of key. If not found returns nil
+      # Get the value of key, if not found, returns nil.
       def get key
         @redis.get key
       end

data/lib/aws-dev-utils/cache.rb

@@ -5,7 +5,7 @@ module AwsDevUtils
   class Cache
     include Singleton
 
-    #for testing
+    # Injectable backend. 
     attr_writer :backend
 
     class << self
@@ -13,14 +13,25 @@ module AwsDevUtils
       def_delegators :fetch
     end
 
+    # Returns a value from the cache for the given key.
+    # If the key can't be found, the block will be run and its result returned and be set in the cache.
+    # @param key [Object]
+    # @param exp [Integer]
+    # @param block [block] - called with no arguments, and returns the new value for the cache (if no cached data is found).
+    # @return [Object] the value from the cache or the result of the block
     def fetch key, exp=60, &block
       get(key) or block.().tap {|x| set(key, x, exp)}
     end
 
+    # Get the value of key. If not found, returns nil
     def get key
       deserialize backend.get key.to_s rescue nil
     end
 
+    # Set key to hold the value and set key to timeout after the a given expiration time(in seconds).
+    # @param key [Object]
+    # @param value [Object]
+    # @param expiration [Time,Integer] - the key-value timeout
     def set key, value, expiration
       backend.set key.to_s, serialize(value), expiration rescue nil
     end

data/lib/aws-dev-utils/cache_wrapper.rb

@@ -4,13 +4,13 @@ module AwsDevUtils
   class CacheWrapper
     include AwsDevUtils::Utils
 
-    # Initialize a new CacheWrapper, Internal use only
-    #
-    # @param client [Aws client, NextTokenWrapper, RetryWrapper]
-    # @param exp [Integer] - the key-value timeout
-    def initialize client, exp=60
+  # Initialize a new CacheWrapper, internal use only.
+  # @param client [Aws client, NextTokenWrapper, RetryWrapper]
+  # @param exp [Integer] - the key-value timeout
+  def initialize client, exp=60, client_name: nil
       @client = client
       @exp = exp
+      @client_name = client_name || client.class.name
     end
 
     def method_missing m, *args, &block
@@ -19,9 +19,13 @@ module AwsDevUtils
 
     private
 
-    def do_call m, args
-      Cache.instance.fetch([m, args.deep_sort, @exp], @exp) {
-        nested_hash(@client.send(m, args))
+    def cache_key m, params
+      [@client_name, m, params.deep_sort, @exp]
+    end
+
+    def do_call m, params
+      Cache.instance.fetch(cache_key(m, params), @exp) {
+        nested_hash(@client.send(m, params))
       }
     end
 

data/lib/aws-dev-utils/client_wrapper.rb

@@ -2,27 +2,37 @@ module AwsDevUtils
   class ClientWrapper
     include AwsDevUtils::Utils
 
+    # Initialize a new ClientWrapper, internal use only
+    # @params [Seahorse::Client::Base] client
+    # @param [Hash] options
+    # @option options [String] next_token max number of requests
+    # @option options [String] retry max number of retries
+    # @option options [String] cache the key-value timeout
     def initialize client, options={}
       @client = client
       @options = options
     end
 
+    # @return ClientWrapper with next_token option
     def with_next_token max=100
       self.class.new(@client, @options.merge(next_token: max))
     end
 
+    # @return ClientWrapper with retry option
     def with_retry max=5
       self.class.new(@client, @options.merge(retry: max))
     end
 
+    # @return ClientWrapper with cache option
     def with_cache exp=60
       self.class.new(@client, @options.merge(cache: exp))
     end
 
     def method_missing m, *args, &block
+      client_name = @client.class.name
       @client = RetryWrapper.new(@client, @options[:retry]) if retry?
       @client = NextTokenWrapper.new(@client, @options[:next_token]) if next_token?
-      @client = CacheWrapper.new(@client, @options[:cache]) if cache?
+      @client = CacheWrapper.new(@client, @options[:cache], client_name: client_name) if cache?
 
       nested_struct(@client.send(m, *args, &block))
     end

data/lib/aws-dev-utils/next_token_wrapper.rb

@@ -1,10 +1,10 @@
 module AwsDevUtils
   class NextTokenWrapper
 
-    # Initialize a new NextTokenWrapper
-    # @params client - Aws client / CacheWrapper / RetryWrapper
-    # @param [Integer] max - max number of requests
-    def initialize client, max=100 #:nodoc:
+    # Initialize a new NextTokenWrapper, internal use only
+    # @params client [Aws client / NextTokenWrapper / RetryWrapper]
+    # @param max [Integer] - max number of requests
+    def initialize client, max=100
       @client = client
       @max = max
     end

data/lib/aws-dev-utils/retry_wrapper.rb

@@ -1,6 +1,9 @@
 module AwsDevUtils
   class RetryWrapper
 
+    # Initialize a new RetryWrapper, internal use only
+    # @params client [Aws client, NextTokenWrapper, RetryWrapper]
+    # @param max_tries [Integer] - max number of retries
     def initialize client, max_tries=5
       @client = client
       @max_tries = max_tries

data/lib/aws-dev-utils/utils.rb

@@ -3,6 +3,8 @@ module AwsDevUtils
 
     module_function
 
+    # Transforms an object to a nested struct.
+    # @return [OpenStruct]
     def nested_struct obj
       case obj
       when Hash
@@ -22,6 +24,8 @@ module AwsDevUtils
       end
     end
 
+    # Transforms an object to a nested hash.
+    # @return [Hash]
     def nested_hash obj
       if obj.kind_of? Array
         obj.map(&method(__method__))

data/lib/aws-dev-utils/version.rb

@@ -1,3 +1,3 @@
 module AwsDevUtils
-  VERSION = '1.4.4'
+  VERSION = '1.4.9'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aws-dev-utils
 version: !ruby/object:Gem::Version
-  version: 1.4.4
+  version: 1.4.9
 platform: ruby
 authors:
-- Infastructure
-autorequire: 
+- Amobee BI Infrastructure
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-08-07 00:00:00.000000000 Z
+date: 2021-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-core
@@ -45,6 +45,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - lib/aws-dev-utils.rb
 - lib/aws-dev-utils/backends/memory.rb
 - lib/aws-dev-utils/backends/redis.rb
@@ -60,7 +62,7 @@ homepage: https://github.com/kontera-technologies/aws-dev-utils
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -75,9 +77,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.8
-signing_key: 
+rubygems_version: 3.0.8
+signing_key:
 specification_version: 4
 summary: Ruby library gem that provides common AWS utilities
 test_files: []