simple_throttle 1.0.7 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bf38f023dce00a87b27e9b2f39d0519a8dbb4abd90b549697be21ed6792bd7f
-  data.tar.gz: 35023bd729899add113084518e63f8ee6975bf71c7a5b12fc0ceb64924ccd207
+  metadata.gz: 47859d64b667fe3e43c8a98ecbce2fa305177530a5d625ed0bd38a500875d268
+  data.tar.gz: 3c0df333efeec1abc8487328a2d131a9ffc2c87273fb5f0ec4048bc340ba1d55
 SHA512:
-  metadata.gz: dfab9a31ebc150ceb5f6b8833efc670357eefa790e60b33156607f7d72155566c300c454fc58368cae15936b8152f2c47e5ed83875ca3b8e0f58f9219d03d5e1
-  data.tar.gz: 4a3bd5605206b8b1e93bcc527c7d3f2dbf22590f23e390c4cb5c75ba7ac3cbe2fef885adffb62006fed54f310eea5804e10c6f319c81c45c8832971d36818718
+  metadata.gz: 88fb81aaa2ac35d7ae5932ccded080c05fe3dd718bcfa9d73b93e8cfd3eb1706b4b5da42b02a06bcd64c861de6f3c98df9bba6005d1b104881b0d5a91f111d06
+  data.tar.gz: b8a94b2c2a24b7c88266a70f052a93a0a6a0fac5b48842e2fd89e56200ebf72c0229defca71ee775cc4a72810a5d4c9c8ee4feac37ab8281d8e67a0a924bf311

data/CHANGELOG.md

@@ -4,39 +4,52 @@ 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.1.0
+
+### Added
+
+- Added `increment!` method to increment the throttle by a given amount and return the current count.
+
 ## 1.0.7
 
 ## Fixed
+
 - Fixed peek method to return the correct value rather than the raw value from Redis.
 
 ### Changed
+
 - Updated repository location and gem owners
 
 ## 1.0.6
 
 ### Added
+
 - Add support for `pause_to_recover` flag on throttles to force calls to the throttle to fail until the process calling them has paused temporarily.
 
 ## 1.0.5
 
 ### Added
+
 - Make loading lua script play better with Redis clusters.
 - Handle failures loading lua script on Redis server to prevent infinite loop.
 
 ## 1.0.4
 
 ### Fixed
-- Fix wait_time method to match the documentation from [bc-swoop](https://github.com/bc-swoop)
+
+- Fix `wait_time` method to match the documentation from [bc-swoop](https://github.com/bc-swoop)
 
 ## 1.0.3
 
 ### Changed
+
 - Ensure that arguments sent to Redis Lua script are cast to integers.
 
 ## 1.0.2
 
 ### Added
-- Throttle insances can now specify the Redis instance to override the global setting.
+
+- Throttle instances can now specify the Redis instance to override the global setting.
 - Redis instance now defaults to the default redis instance: `Redis.new`.
 - Optimize loading LUA script to Redis; now done globally instead of per throttle instance.
 
@@ -44,10 +57,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## 1.0.1
 
 ### Added
+
 - Added mutex in `SimpleThrottle.add` to ensure thread safety when adding global throttles.
 
 
 ## 1.0.0
 
 ### Added
+
 - Simple Redis backed throttle for Ruby.

data/README.md

@@ -1,3 +1,7 @@
+# Simple Throttle
+
+[![Continuous Integration](https://github.com/bdurand/simple_throttle/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/simple_throttle/actions/workflows/continuous_integration.yml)
+[![Regression Test](https://github.com/bdurand/simple_throttle/actions/workflows/regression_test.yml/badge.svg)](https://github.com/bdurand/simple_throttle/actions/workflows/regression_test.yml)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
 
 This gem provides a very simple throttling mechanism backed by Redis for limiting access to a resource. The throttle can be thought of as a limit on the number of calls in a set time frame (i.e. 100 calls per hour).
@@ -37,6 +41,17 @@ Calling `allowed!` will return `true` if the throttle limit has not yet been rea
 
 The throttle data is kept in redis as a list of timestamps and will be auto expired if it falls out of use. The thottles time windows are rolling time windows and more calls will be allowed as soon as possible. So, if you have a throttle of, 100 requests per hour, and the throttle kicks in, you will be able to make the next throttled call one hour after the first call being tracked, not one hour after the last call.
 
+You can also increment the throttle yourself with the `increment!` method. This will increment the throttle by the given amount and return the current count. The count will be capped by the throttle limit since excess requests beyond the limit are not tracked in Redis for performance reasons.
+
+```ruby
+count = throttle.increment!
+if count <= throttle.limit
+  do_something
+else
+  raise "Too many requests: #{count}"
+end
+```
+
 ### Pause to recover option
 
 Throttles can also specify a `pause_to_recover` option set when they are created. When this flag is set, once a throttle check fails, it will continue to fail until the rate at which it is called drops below the maximum rate allowed by the throttle. This is designed for use where you want to detect run away processes constantly hitting a service. Without this set, the process would be able to utilize the resource up to the set limit. With it set, the process would need to pause temporarily to succeed again.

data/VERSION

@@ -1 +1 @@
-1.0.7
+1.1.0

data/lib/simple_throttle.rb

@@ -15,8 +15,8 @@ class SimpleThrottle
     local limit = tonumber(ARGV[1])
     local ttl = tonumber(ARGV[2])
     local now = ARGV[3]
-    local push = tonumber(ARGV[4])
-    local pause_to_recover = tonumber(ARGV[5])
+    local pause_to_recover = tonumber(ARGV[4])
+    local amount = tonumber(ARGV[5])
 
     local size = redis.call('llen', list_key)
     if size >= limit then
@@ -31,12 +31,22 @@ class SimpleThrottle
       end
     end
 
-    if push > 0 and (size < limit or (size == limit and pause_to_recover > 0)) then
-      redis.call('rpush', list_key, now)
+    if pause_to_recover > 0 then
+      limit = limit + 1
+    end
+
+    if size + amount > limit then
+      amount = (limit - size) + 1
+    end
+
+    if size < limit then
+      for i = 1, amount do
+        redis.call('rpush', list_key, now)
+      end
       redis.call('pexpire', list_key, ttl)
     end
 
-    return size
+    return size + amount
   LUA
 
   @lock = Mutex.new
@@ -81,7 +91,7 @@ class SimpleThrottle
     # @yieldreturn [Redis]
     # @return [void]
     def set_redis(client = nil, &block)
-      @redis_client = (client || block)
+      @redis_client = (client || block) # rubocop:disable Style/RedundantParentheses
     end
 
     # Return the Redis instance where the throttles are stored.
@@ -142,8 +152,26 @@ class SimpleThrottle
   #
   # @return [Boolean]
   def allowed!
-    size = current_size(true)
-    size < limit
+    size = increment!
+    size <= limit
+  end
+
+  # Increment the throttle by the specified and return the current size. Because
+  # how the throttle is implemented in Redis, the return value will always max
+  # out at the throttle limit + 1 or, if the pause to recover option is set, limit + 2.
+  #
+  # @param amount [Integer] amount to increment the throttle by
+  # @return [Integer]
+  def increment!(amount = 1)
+    pause_to_recover_arg = (@pause_to_recover ? 1 : 0)
+    time_ms = (Time.now.to_f * 1000).round
+    ttl_ms = (ttl * 1000).ceil
+    self.class.send(
+      :execute_lua_script,
+      redis: redis_client,
+      keys: [redis_key],
+      args: [limit, ttl_ms, time_ms, pause_to_recover_arg, amount]
+    )
   end
 
   # Reset a throttle back to zero.
@@ -188,16 +216,6 @@ class SimpleThrottle
     end
   end
 
-  # Evaluate and execute a Lua script on the redis server that returns the number calls currently being tracked.
-  # If push is set to true then a new item will be added to the list.
-  def current_size(push)
-    push_arg = (push ? 1 : 0)
-    pause_to_recover_arg = (@pause_to_recover ? 1 : 0)
-    time_ms = (Time.now.to_f * 1000).round
-    ttl_ms = (ttl * 1000).ceil
-    self.class.send(:execute_lua_script, redis: redis_client, keys: [redis_key], args: [limit, ttl_ms, time_ms, push_arg, pause_to_recover_arg])
-  end
-
   def redis_key
     "simple_throttle.#{name}"
   end

data/simple_throttle.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name = "simple_throttle"
-  spec.version = File.read(File.expand_path("../VERSION", __FILE__)).strip
+  spec.version = File.read(File.expand_path("VERSION", __dir__)).strip
   spec.authors = ["Brian Durand"]
   spec.email = ["bbdurand@gmail.com"]
 
@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
     gemfiles/
     spec/
   ]
-  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+  spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject { |f| ignore_files.any? { |path| f.start_with?(path) } }
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_throttle
 version: !ruby/object:Gem::Version
-  version: 1.0.7
+  version: 1.1.0
 platform: ruby
 authors:
 - Brian Durand
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-31 00:00:00.000000000 Z
+date: 2024-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -70,7 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Simple redis backed throttling mechanism to limit access to a resource