double_restraint 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f0ee8109419ddc8e93ea3685a0d2f32c3d8b96383afe4c4330bbc866d9ee566
-  data.tar.gz: 8c92f8eabaae7b7b4e0754d5e968d3fc1ecb045f5b4aa04c2d323f167551f467
+  metadata.gz: ea9dbcbe1d5da4480324c5dcfa993aaa72e58786430200ee0aaedbd844d341ba
+  data.tar.gz: 42201e52acde9d9ca90b5c0c4ded0350af3910f7aca3e8f97c59010929284030
 SHA512:
-  metadata.gz: a7e55a6862bfda0b56a445b37af3fe3d0b486cd2ffde2e4ab2246700496cbe3017f3c737e9c507d1ab3ede613d34fc2137c8679356345a74757bc257010f32a0
-  data.tar.gz: b80b29ec078b8fe3b48bbb4e5d549684a7e3f56157d29ab58d6fd09e2a20679513ebe250416238b871421f608146271ca07b66c461841a151f095479ce8231f3
+  metadata.gz: de78ad1954fc63e5936f0d26d4d02daf188cb594dc366b8dcf62a8941ee574fd06d7d1200ffb88ace43a4ab3c919a945ad738d70ef4af7d0dfea3b1f1db32ffe
+  data.tar.gz: 31dc3d878fde21db6c4a636129bb6acc8ef2b11573b0ded621b840968c456ec5b9f2972a8fc104c978af32dc3a43abcc92d358eaa56bebc411d2b82a81b7a761

data/CHANGELOG.md

@@ -4,10 +4,23 @@ 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.1]
+## 1.0.2
+
+### Fixed
+
+- Timeout errors raised by the underlying `Restrainer` Redis calls no longer trigger the long running retry; only timeout errors raised by the block itself do. Previously a matching error raised while releasing the throttle could re-run a block that had already succeeded.
+- Timeout errors that are not `StandardError` subclasses now correctly trigger the long running retry.
+- `limit: 0` now means no executions are allowed (matching `Restrainer` semantics) instead of silently meaning unlimited. Use `limit: nil` (the default) for no limit.
+- The orphaned lock expiration on the underlying restrainers is now derived from `long_running_timeout` so that blocks legitimately running longer than 60 seconds no longer allow the concurrency limits to be exceeded.
+
+## 1.0.1
+
 ### Added
+
 - Methods to expose the pool limits, timeouts and current in use sizes.
 
-## [1.0.0]
+## 1.0.0
+
 ### Added
-- Everything!
+
+- Initial release.

data/README.md

@@ -2,21 +2,22 @@
 
 [![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)
+[![Gem Version](https://badge.fury.io/rb/double_restraint.svg)](https://badge.fury.io/rb/double_restraint)
 
-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.
+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/bdurand/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.
+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 of your application threads will 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.
+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 service fail fast. However, if some requests to the service take just a little longer even in a healthy 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:
+With the [restrainer gem](https://github.com/bdurand/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
+  restrainer.throttle do
     MyWebService.new.call(arguments)
   end
 rescue Restrainer::ThrottledError
@@ -26,7 +27,7 @@ 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.
+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 healthy system.
 
 ```ruby
 restraint = DoubleRestraint.new("MyWebService", timeout: 0.5, long_running_timeout: 5.0, long_running_limit: 5)
@@ -40,12 +41,12 @@ 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_timeout` value should be set to a higher value that works for all requests in a healthy 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 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 see 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`.
 
@@ -61,7 +62,7 @@ By default, a timeout is identified by any error that inherits from `Timeout::Er
 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).
+Finally, you need to specify the Redis instance to use. By default this uses the value specified for the [restrainer gem](https://github.com/bdurand/restrainer).
 
 ```ruby
 # set the global Redis instance
@@ -74,10 +75,25 @@ 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)
+restraint = DoubleRestraint.new("MyWebService", redis: Redis.new(url: redis_url), timeout: 0.5, long_running_timeout: 5.0, long_running_limit: 5)
 ```
 
-You can peek at the current pool sizes as well if
+You can peek at the current pool sizes as well if you want:
+
+```ruby
+# Number of processes currently using a slot in the default pool
+restraint.default_pool_size
+
+# Number of processes currently using a slot in the long running pool
+restraint.long_running_pool_size
+
+# Get the percentage capacity being used as a whole. Note that this only
+# makes sense if a limit is set on the default pool (default_pool_limit
+# returns -1 when the pool is unlimited).
+total_pool_used = restraint.default_pool_size + restraint.long_running_pool_size
+total_pool_capacity = restraint.default_pool_limit + restraint.long_running_pool_limit
+total_pool_used.to_f / total_pool_capacity
+```
 
 ## Installation
 

data/VERSION

@@ -1 +1 @@
-1.0.1
+1.0.2

data/double_restraint.gemspec

@@ -8,6 +8,12 @@ Gem::Specification.new do |spec|
   spec.homepage = "https://github.com/bdurand/double_restraint"
   spec.license = "MIT"
 
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md"
+  }
+
   # 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[
@@ -24,7 +30,7 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "restrainer"
+  spec.add_dependency "restrainer", ">= 1.1.3"
 
   spec.add_development_dependency "bundler"
 

data/lib/double_restraint.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "timeout"
 require "restrainer"
 
 class DoubleRestraint
@@ -8,11 +9,11 @@ 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
+  #        the block times out the first time it is executed.
+  # @param long_running_limit [Integer] The maximum number of concurrent executions of the block
   #        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 limit [Integer] The maximum number of concurrent executions of the block with the
+  #        initial timeout across all processes. If this is nil, then no limit will be applied.
   # @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.
@@ -22,9 +23,15 @@ class DoubleRestraint
     @timeout = timeout
     @long_running_timeout = long_running_timeout
     @timeout_errors = Array(timeout_errors)
-    limit = -1 if limit.to_i <= 0
-    @restrainer = Restrainer.new("DoubleRestrainer(#{name})", limit: limit, redis: redis)
-    @long_running_restrainer = Restrainer.new("DoubleRestrainer(#{name}).long_running", limit: long_running_limit, redis: redis)
+    limit = -1 if limit.nil?
+    # Slots in the underlying restrainers expire as a safeguard against orphaned locks,
+    # so the expiration must comfortably exceed the longest time a block can legitimately
+    # hold a slot.
+    restrainer_timeout = [60, long_running_timeout.to_f * 2].max
+    # The restrainer names use "DoubleRestrainer" rather than "DoubleRestraint" for
+    # backward compatibility with the Redis keys created by earlier versions of the gem.
+    @restrainer = Restrainer.new("DoubleRestrainer(#{name})", limit: limit, timeout: restrainer_timeout, redis: redis)
+    @long_running_restrainer = Restrainer.new("DoubleRestrainer(#{name}).long_running", limit: long_running_limit, timeout: restrainer_timeout, redis: redis)
   end
 
   # Execute a block of code. The block will be yielded with the timeout value. If the block raises
@@ -32,21 +39,26 @@ class DoubleRestraint
   # 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(&block)
-    begin
-      @restrainer.throttle do
-        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
+  # @return [Object] the value returned by the block.
+  # @raise [Restrainer::ThrottledError] if too many concurrent processes are trying to use the restraint.
+  def execute
+    timed_out = false
+    result = @restrainer.throttle do
+      yield @timeout
+    rescue *@timeout_errors
+      # Just flag the timeout here so the retry happens after the throttle
+      # block exits and releases its slot in the default pool.
+      timed_out = true
+      nil
+    end
+
+    if timed_out
+      result = @long_running_restrainer.throttle do
+        yield @long_running_timeout
       end
     end
+
+    result
   end
 
   # Get the current size of the default pool. This can be useful in

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: double_restraint
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Brian Durand
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-02-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: restrainer
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.1.3
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -38,7 +37,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
 email:
 - bbdurand@gmail.com
 executables: []
@@ -46,7 +44,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
+- MIT-LICENSE.txt
 - README.md
 - VERSION
 - double_restraint.gemspec
@@ -54,8 +52,10 @@ files:
 homepage: https://github.com/bdurand/double_restraint
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/bdurand/double_restraint
+  source_code_uri: https://github.com/bdurand/double_restraint
+  changelog_uri: https://github.com/bdurand/double_restraint/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -70,8 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Throttling mechanism for safely dealing with external resources so that latency
   does not take down your application.