double_restraint 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 730e777e36c39bfc23ff335c32c5ed3afcc92f939496546a27e26c16cb755a7b
+  data.tar.gz: 68a039424903a839c46defb56535a33a793ab8e044ed62e986ff0b2fe5f4ffef
+SHA512:
+  metadata.gz: fd3bd50d0e03ba15d9a043e54f877e3c1828d546d54b1f2751adfc5aac0f4c8da88eda18e7af4c7597bf6203272f7748b383e2c24ea548e56e72b3b9a83ac0d8
+  data.tar.gz: 597684fa2b5eefb6f6ae9c5de1fbdeb353846368a209ba606828a2b670a520398400ad3703ae5f0935445d21f3bb58bb62cb6454c045c347dc12b3a897cf5b5c

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0]
+### Added
+- Everything!

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Brian Durand
+
+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,106 @@
+# Double Restraint
+
+[![Continuous Integration](https://github.com/bdurand/double_restraint/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/double_restraint/actions/workflows/continuous_integration.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+
+This gem implements a pattern for interacting with external services in a way that prevents performance issues with those services from taking down your application. It builds atop the [restrainer gem](https://github.com/weheartit/restrainer) which requires a Redis server to coordinate processes.
+
+## Usage
+
+Suppose you have a web application that calls a web service for something, and at some point that web service starts to have latency issues and requests take several seconds to return. Eventually most your application threads will be be waiting on the web service and your application will be completely unresponsive.
+
+If the external service uses timeouts, you could mitigate the issue of locking up your application by setting a low timeout so that requests to the sevice fail fast. However, if some requests to the service take just a little longer even in a health system, then you will be artificially preventing these requests from succeeding.
+
+With the [restrainer gem](https://github.com/weheartit/restrainer) you can throttle the number of concurrent requests to a service so that, if there is a problem with that service, only a limited number of application threads would be affected:
+
+```ruby
+restrainer = Restrainer.new("MyWebService", limit: 10)
+begin
+  restainer.throttle do
+    MyWebService.new.call(arguments)
+  end
+rescue Restrainer::ThrottledError
+  puts "Too many concurrent calls to MyWebService"
+end
+```
+
+However, this can lead to problems if you set the limit too low. You could end up in a situation where peak traffic sends more requests than the limit you set. This will end up artificially limiting the external calls and returning errors to users.
+
+This gem combines both solutions and lets you set two levels of timeouts and a limit on how many concurrent requests can use the longer timeout. You can be more aggressive with both your fail fast timeout and the limit on concurrent processes without affecting requests in a health system.
+
+```ruby
+restraint = DoubleRestraint.new("MyWebService", timeout: 0.5, long_running_timeout: 5.0, long_running_limit: 5)
+begin
+  restraint.execute do |timeout|
+    MyWebService.new(timeout: timeout).call(arguments)
+  end
+rescue Restrainer::ThrottledError
+  puts "Too many concurrent calls to MyWebService"
+end
+```
+
+* The `timeout` value should be set to a low value that works for most requests in a healthy system.
+* The `long_running_timeout` value should be set to a higher value that works for all requests in a health system.
+* The `long_running_limit` value is the maximum number of concurrent requests that are allowed using the higher timeout.
+
+The `execute` call will call the block with the `timeout` value. If the block raises a timeout error, then it will be called again with the `long_running_timeout` value inside a `Restrainer`. If there are too many concurrent requests, then a `Restrainer::ThrottledError` will be raised.
+
+The effect of this is that if there are latency issues in `MyWebService`, then the requests will fail fast. Only a handful of requests will be allowed to execute with the higher timeout value so the impact on the overall system will be very limited. On a healthy system, you shouldn't seen any artificially generated errors as long as your `timeout` is set properly.
+
+The `execute` block **must** be idempotent since it can be run twice by one call to `execute`.
+
+You can also set a restraint on the initial execution with the lower timeout by specifying the `limit` parameter.
+
+```ruby
+restraint = DoubleRestraint.new("MyWebService", limit: 50, timeout: 0.5, long_running_timeout: 5.0, long_running_limit: 5)
+```
+
+By default, a timeout is identified by any error that inherits from `Timeout::Error`. You may need to specify what constitutes a timeout error in your block of code, though. For instance, if you code uses Faraday to make an HTTP requests, then you would need to specify that timeouts are identified by `Faraday::TimeoutError`.
+
+```ruby
+restraint = DoubleRestraint.new("MyWebService", timeout_errors: [Faraday::TimeoutError], timeout: 0.5, long_running_timeout: 5.0, long_running_limit: 5)
+```
+
+Finally, you need to specify the Redis instance to use. By default this uses the value specified for the [restrainer gem](https://github.com/weheartit/restrainer).
+
+```ruby
+# set the global Redis instance
+Restrainer.redis = Redis.new(url: redis_url)
+
+# or use a block to specify a value that is yielded at runtime
+Restrainer.redis{ connection_pool.redis }
+```
+
+However, you can also specify the Redis instance directly on the `DoubleRestraint` instance.
+
+```ruby
+restraint = DoubleRestraint.new("MyWebService", redis: Redis.new(url: redis_url)), timeout: 0.5, long_running_timeout: 5.0, long_running_limit: 5)
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "double_restraint"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install double_restraint
+```
+
+## Contributing
+
+Open a pull request on GitHub.
+
+Please use the [standardrb](https://github.com/testdouble/standard) syntax and lint your code with `standardrb --fix` before submitting.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/double_restraint.gemspec

@@ -0,0 +1,32 @@
+Gem::Specification.new do |spec|
+  spec.name = "double_restraint"
+  spec.version = File.read(File.expand_path("VERSION", __dir__)).strip
+  spec.authors = ["Brian Durand"]
+  spec.email = ["bbdurand@gmail.com"]
+
+  spec.summary = "Throttling mechanism for safely dealing with external resources so that latency does not take down your application."
+  spec.homepage = "https://github.com/bdurand/double_restraint"
+  spec.license = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  ignore_files = %w[
+    .
+    Gemfile
+    Gemfile.lock
+    Rakefile
+    bin/
+    spec/
+  ]
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "restrainer"
+
+  spec.add_development_dependency "bundler"
+
+  spec.required_ruby_version = ">= 2.5"
+end

data/lib/double_restraint.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "restrainer"
+
+class DoubleRestraint
+  # @param name [String, Symbol] The name of the restraint.
+  # @param timeout [Numeric] The first timeout that will be yielded to the block.
+  # @param long_running_timeout [Numeric] The timeout that will be yielded to the block if
+  #        the block times out the first time it is excuted.
+  # @param long_running_limit [Integer] The maximum number of times the block can be run
+  #        with the long running timeout across all processes.
+  # @param limit [Integer] The maximum of number of times the block can be run with the initial
+  #        timeout across all processes.
+  # @param timeout_errors [Array<Module>] List of errors that will be considered a timeout.
+  #        This needs to be customized depending on what the code in the block could throw to
+  #        indicate a timeout has occurred.
+  # @param redis [Redis] Redis connection to use.
+  #        If this is not set, the default value set for `Restrainer.redis` will be used.
+  def initialize(name, timeout:, long_running_timeout:, long_running_limit:, limit: nil, timeout_errors: [Timeout::Error], redis: nil)
+    @timeout = timeout
+    @long_running_timeout = long_running_timeout
+    @timeout_errors = Array(timeout_errors)
+    @restrainer = Restrainer.new("DoubleRestrainer(#{name})", limit: limit, redis: redis) if limit
+    @long_running_restrainer = Restrainer.new("DoubleRestrainer(#{name}).long_running", limit: long_running_limit, redis: redis)
+  end
+
+  # Execute a block of code. The block will be yielded with the timeout value. If the block raises
+  # a timeout error, then it will be called again with the long running timeout. The code in the block
+  # must be idempotent since it can be run twice.
+  # @yieldparam [Numeric] the timeout value to use in the block.
+  # @raise [Restrainer::ThrottleError] if too many concurrent processes are trying to use the restraint.
+  def execute
+    begin
+      if @restrainer
+        @restrainer.throttle do
+          yield @timeout
+        end
+      else
+        yield @timeout
+      end
+    rescue => e
+      if @timeout_errors.any? { |error_class| e.is_a?(error_class) }
+        @long_running_restrainer.throttle do
+          yield @long_running_timeout
+        end
+      else
+        raise e
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: double_restraint
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brian Durand
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-03-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: restrainer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- bbdurand@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- VERSION
+- double_restraint.gemspec
+- lib/double_restraint.rb
+homepage: https://github.com/bdurand/double_restraint
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Throttling mechanism for safely dealing with external resources so that latency
+  does not take down your application.
+test_files: []