simple_throttle 1.1.0 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47859d64b667fe3e43c8a98ecbce2fa305177530a5d625ed0bd38a500875d268
-  data.tar.gz: 3c0df333efeec1abc8487328a2d131a9ffc2c87273fb5f0ec4048bc340ba1d55
+  metadata.gz: bfa3230d5cc40054d4745124ca652988cda2d3443d46693cf4de2611e1c6eac1
+  data.tar.gz: c75e2af15e6a114f26f705e48874e4b70bb05efbd2f68d9c52f0236d8c9e9ca2
 SHA512:
-  metadata.gz: 88fb81aaa2ac35d7ae5932ccded080c05fe3dd718bcfa9d73b93e8cfd3eb1706b4b5da42b02a06bcd64c861de6f3c98df9bba6005d1b104881b0d5a91f111d06
-  data.tar.gz: b8a94b2c2a24b7c88266a70f052a93a0a6a0fac5b48842e2fd89e56200ebf72c0229defca71ee775cc4a72810a5d4c9c8ee4feac37ab8281d8e67a0a924bf311
+  metadata.gz: c66cd0cac05fa9edf641c9b63acd664b0631421f8f31cd3937d2f2d67f7dc13cfe6764b30a3feb6963b50b4795594d3109c58de757c8b866dd82cc1a9627383c
+  data.tar.gz: 2312af9ccb5e69534195098109d3965fa6e1b92ea9e4bd8f92e591fecaa85359a6ad5ff1e6fbc3a56cc6c8d2c6479701b55a3f3e5c76d3801ce060cf746d76a2

data/CHANGELOG.md

@@ -4,6 +4,26 @@ 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.2
+
+### Fixed
+
+- Fixed `wait_time` returning negative values when the throttle list held more than `limit` entries (possible after `increment!` or with `pause_to_recover`); it now reads the entry that actually frees a slot, handles a concurrently expired key, and never returns a value below zero.
+- Fixed the throttle timestamps to use the Redis server clock instead of the calling process clock so that entries are ordered consistently and cleanup works correctly when multiple clients with skewed clocks share a throttle. `peek` and `wait_time` also read the Redis server clock so clock skew cannot cause miscounts or wait times longer than the ttl; `wait_time` is additionally capped at the ttl.
+- Fixed `SimpleThrottle.new` to always store the name as a frozen `String` regardless of the argument type.
+
+### Changed
+
+- Throttle time is now measured entirely by the Redis server clock. Manipulating time in the calling process (i.e. with Timecop or by stubbing `Time.now`) no longer has any effect on throttles; tests need to use a short `ttl` and actually sleep. Reading the server clock does not add a round trip; `peek` and `wait_time` pipeline it with the read of the timestamp list.
+- `increment!` now raises `ArgumentError` when given a non-positive amount instead of corrupting the count.
+- Hardened thread safety of the global throttle registry and lazily-initialized Redis client.
+
+## 1.1.1
+
+### Fixed
+
+- Fixed `increment!` method to return the correct value after removing expired requests rather than the raw count from Redis.
+
 ## 1.1.0
 
 ### Added

data/README.md

@@ -1,8 +1,8 @@
 # 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)
+[![Gem Version](https://badge.fury.io/rb/simple_throttle.svg)](https://badge.fury.io/rb/simple_throttle)
 
 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).
 
@@ -78,7 +78,29 @@ end
 
 ### Redis requirement
 
-Redis server 2.6 or greater is required for this code.
+The `redis` gem version 4.5 or greater is required. Versions 4.5, 5.x, and 6.x are all supported and tested.
+
+Redis server 3.2 or greater is required. The Lua script that maintains the throttle reads the server clock and then writes to the throttle list, which is only allowed under effects replication.
+
+### Time is measured by the Redis server clock
+
+All throttle timestamps come from the Redis server's clock rather than the clock of the process calling the throttle. This is deliberate: a throttle is usually shared by many processes, and if each one stamped entries with its own clock, then clock skew between them would corrupt the ordering of the list and cause entries to expire too early or too late. Using a single clock means every client agrees on the time window no matter how skewed their local clocks are.
+
+There are two consequences worth knowing about:
+
+- **Manipulating time in tests has no effect on throttles.** Tools like [Timecop](https://github.com/travisjeffery/timecop), `ActiveSupport::Testing::TimeHelpers`, or stubbing `Time.now` only change the clock inside your Ruby process. The Redis server is a separate process and keeps reporting the real time, so freezing or traveling through time will not expire throttle entries or change what `wait_time` returns. To test throttle expiration, create the throttle with a very short `ttl` and actually `sleep`:
+
+  ```ruby
+  throttle = SimpleThrottle.new("test", limit: 1, ttl: 0.1)
+  expect(throttle.allowed!).to eq true
+  expect(throttle.allowed!).to eq false
+  sleep(0.15)
+  expect(throttle.allowed!).to eq true
+  ```
+
+  Use `reset!` to clear a throttle between tests.
+
+- **Reading the server clock does not cost an extra round trip.** `allowed!` and `increment!` read the clock inside the Lua script they already run, and `peek` and `wait_time` pipeline the clock read together with the read of the timestamp list. Every operation is still a single round trip to Redis.
 
 ## Installation
 

data/VERSION

@@ -1 +1 @@
-1.1.0
+1.1.2

data/lib/simple_throttle.rb

@@ -11,16 +11,23 @@ class SimpleThrottle
   # then the current entry will be added. The list is marked to expire with the oldest entry so
   # there's no need to cleanup the lists.
   LUA_SCRIPT = <<~LUA
+    redis.replicate_commands()
+
     local list_key = KEYS[1]
     local limit = tonumber(ARGV[1])
     local ttl = tonumber(ARGV[2])
-    local now = ARGV[3]
-    local pause_to_recover = tonumber(ARGV[4])
-    local amount = tonumber(ARGV[5])
+    local pause_to_recover = tonumber(ARGV[3])
+    local amount = tonumber(ARGV[4])
+    local cleanup = tonumber(ARGV[5])
+
+    -- Use the Redis server clock so timestamps are consistent and monotonic
+    -- across all clients regardless of individual machine clock skew.
+    local time = redis.call('time')
+    local now = (tonumber(time[1]) * 1000) + math.floor(tonumber(time[2]) / 1000)
 
     local size = redis.call('llen', list_key)
-    if size >= limit then
-      local expired = tonumber(now) - ttl
+    if size >= limit or (cleanup > 0 and size > 0) then
+      local expired = now - ttl
       while size > 0 do
         local t = redis.call('lpop', list_key)
         if tonumber(t) > expired then
@@ -50,6 +57,9 @@ class SimpleThrottle
   LUA
 
   @lock = Mutex.new
+  @redis_client = nil
+  @script_sha_1 = nil
+  @throttles = {}.freeze
 
   class << self
     # Add a global throttle that can be referenced later with the [] method.
@@ -62,12 +72,15 @@ class SimpleThrottle
     # @param pause_to_recover [Boolean] require processes calling the throttle
     #   to pause at least temporarily before freeing up the throttle. If this is true,
     #   then a throttle called constantly with no pauses will never free up.
-    # @param redis [Redis, Proc] Redis instance to use or a Proc that yields a Redos instance
+    # @param redis [Redis, Proc] Redis instance to use or a Proc that yields a Redis instance
     # @return [void]
     def add(name, ttl:, limit:, pause_to_recover: false, redis: nil)
       @lock.synchronize do
-        @throttles ||= {}
-        @throttles[name.to_s] = new(name, limit: limit, ttl: ttl, pause_to_recover: pause_to_recover, redis: redis)
+        # Copy-on-write so that lock-free readers in `[]` always see a
+        # fully-populated, immutable hash and never a partially rehashed one.
+        throttles = @throttles.dup
+        throttles[name.to_s] = new(name, limit: limit, ttl: ttl, pause_to_recover: pause_to_recover, redis: redis)
+        @throttles = throttles.freeze
       end
     end
 
@@ -76,9 +89,9 @@ class SimpleThrottle
     # @param name [String, Symbol] name of the throttle
     # @return [SimpleThrottle]
     def [](name)
-      if defined?(@throttles) && @throttles
-        @throttles[name.to_s]
-      end
+      # Assign then read for thread safety.
+      throttles = @throttles
+      throttles[name.to_s] if throttles
     end
 
     # Set the Redis instance to use for maintaining the throttle. This can either be set
@@ -98,11 +111,12 @@ class SimpleThrottle
     #
     # @return [Redis]
     def redis
-      @redis_client ||= Redis.new
-      if @redis_client.is_a?(Proc)
-        @redis_client.call
+      @lock.synchronize { @redis_client ||= Redis.new } unless @redis_client
+      client = @redis_client
+      if client.is_a?(Proc)
+        client.call
       else
-        @redis_client
+        client
       end
     end
 
@@ -110,14 +124,15 @@ class SimpleThrottle
 
     def execute_lua_script(redis:, keys:, args:)
       client = redis
-      @script_sha_1 ||= client.script(:load, LUA_SCRIPT)
+      sha1 = @script_sha_1
+      sha1 ||= @lock.synchronize { @script_sha_1 ||= client.script(:load, LUA_SCRIPT) }
       attempts = 0
 
       begin
-        client.evalsha(@script_sha_1, Array(keys), Array(args))
+        client.evalsha(sha1, Array(keys), Array(args))
       rescue Redis::CommandError => e
         if e.message.include?("NOSCRIPT") && attempts < 2
-          @script_sha_1 = client.script(:load, LUA_SCRIPT)
+          sha1 = @lock.synchronize { @script_sha_1 = client.script(:load, LUA_SCRIPT) }
           attempts += 1
           retry
         else
@@ -137,10 +152,9 @@ class SimpleThrottle
   # @param pause_to_recover [Boolean] require processes calling the throttle
   #   to pause at least temporarily before freeing up the throttle. If this is true,
   #   then a throttle called constantly with no pauses will never free up.
-  # @param redis [Redis, Proc] Redis instance to use or a Proc that yields a Redos instance
+  # @param redis [Redis, Proc] Redis instance to use or a Proc that yields a Redis instance
   def initialize(name, ttl:, limit:, pause_to_recover: false, redis: nil)
-    @name = name.to_s
-    @name = name.dup.freeze unless name.frozen?
+    @name = name.to_s.dup.freeze
     @limit = limit.to_i
     @ttl = ttl.to_f
     @pause_to_recover = !!pause_to_recover
@@ -152,7 +166,7 @@ class SimpleThrottle
   #
   # @return [Boolean]
   def allowed!
-    size = increment!
+    size = add_request(1, false)
     size <= limit
   end
 
@@ -160,18 +174,13 @@ class SimpleThrottle
   # 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
+  # @param amount [Integer] amount to increment the throttle by (must be positive)
   # @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]
-    )
+    amount = amount.to_i
+    raise ArgumentError, "amount must be a positive integer" if amount < 1
+
+    add_request(amount, true)
   end
 
   # Reset a throttle back to zero.
@@ -185,8 +194,8 @@ class SimpleThrottle
   #
   # @return [Integer]
   def peek
-    timestamps = redis_client.lrange(redis_key, 0, -1).collect(&:to_i)
-    min_timestamp = ((Time.now.to_f - ttl) * 1000).ceil
+    timestamps, now = timestamps_with_server_time
+    min_timestamp = ((now - ttl) * 1000).ceil
     timestamps.count { |t| t > min_timestamp }
   end
 
@@ -196,13 +205,19 @@ class SimpleThrottle
   #
   # @return [Float]
   def wait_time
-    if peek < limit
+    timestamps, now = timestamps_with_server_time
+    min_timestamp = ((now - ttl) * 1000).ceil
+    if timestamps.count { |t| t > min_timestamp } < limit
       0.0
     else
-      first = redis_client.lindex(redis_key, 0).to_f / 1000.0
-      delta = Time.now.to_f - first
-      delta = 0.0 if delta < 0
-      ttl - delta
+      # The entry that frees up a slot is the limit-th newest (index -limit),
+      # not the head of the list, since the list can legitimately hold more
+      # than `limit` entries (increment! and pause_to_recover both add extras).
+      oldest = timestamps[-limit]
+      return 0.0 if oldest.nil?
+      first = oldest.to_f / 1000.0
+      wait = ttl - (now - first)
+      wait.clamp(0.0, ttl)
     end
   end
 
@@ -219,4 +234,31 @@ class SimpleThrottle
   def redis_key
     "simple_throttle.#{name}"
   end
+
+  # The Lua script stores timestamps from the Redis server clock, so reads
+  # must be measured against that same clock rather than the local one. Both
+  # values are fetched in a single pipeline so that reading the clock doesn't
+  # cost an extra round trip.
+  #
+  # @return [Array(Array<Integer>, Float)] the tracked timestamps in
+  #   milliseconds and the current Redis server time in seconds.
+  def timestamps_with_server_time
+    timestamps, time = redis_client.pipelined do |pipeline|
+      pipeline.lrange(redis_key, 0, -1)
+      pipeline.time
+    end
+    seconds, microseconds = time
+    [timestamps.collect(&:to_i), seconds.to_i + (microseconds.to_i / 1_000_000.0)]
+  end
+
+  def add_request(amount, cleanup)
+    pause_to_recover_arg = (@pause_to_recover ? 1 : 0)
+    ttl_ms = (ttl * 1000).ceil
+    self.class.send(
+      :execute_lua_script,
+      redis: redis_client,
+      keys: [redis_key],
+      args: [limit, ttl_ms, pause_to_recover_arg, amount, (cleanup ? 1 : 0)]
+    )
+  end
 end

data/simple_throttle.gemspec

@@ -8,6 +8,12 @@ Gem::Specification.new do |spec|
   spec.homepage = "https://github.com/bdurand/simple_throttle"
   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[
@@ -26,9 +32,7 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "redis"
-
-  spec.add_development_dependency "bundler"
+  spec.add_dependency "redis", ">= 4.5"
 
-  spec.required_ruby_version = ">= 2.5"
+  spec.required_ruby_version = ">= 2.6"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: simple_throttle
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.2
 platform: ruby
 authors:
 - Brian Durand
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-30 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -16,29 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '4.5'
   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:
+        version: '4.5'
 email:
 - bbdurand@gmail.com
 executables: []
@@ -54,8 +38,10 @@ files:
 homepage: https://github.com/bdurand/simple_throttle
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  homepage_uri: https://github.com/bdurand/simple_throttle
+  source_code_uri: https://github.com/bdurand/simple_throttle
+  changelog_uri: https://github.com/bdurand/simple_throttle/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -63,15 +49,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Simple redis backed throttling mechanism to limit access to a resource
 test_files: []