throttle_machines 0.2.4 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6450b4499ed28a6520bdc5d51a2c5bc7fcc55ba8e1f1e327def0ca9ab5c80d62
-  data.tar.gz: af1addd1f524c9f5663f3f241ce15bfb1aa9a6b5365463f3c9d453a9e03f0b05
+  metadata.gz: 3dd617a00122348c117c538ed1e1b2242763a619c28fed7bc6b701a4440c83fd
+  data.tar.gz: 692ac18d365391f16c16b81292672f223024e00dc92abd9c8a50020cf04a17bc
 SHA512:
-  metadata.gz: 564076859ef7219e48060400a26295cffc830a74fbf82d757766753e19d2020fce390ce8b91b9daf996147689dd47fec0911037a34a0208cd160ec3d6009ac70
-  data.tar.gz: 39590d460f59b66a700487146ea3309aa8df4d9f3b31e0248acb1b0748bc04b3a26f9a55f52f18b4beb3fca7618a8142092b4d434f45a4ce833a265d8e2c5fdb
+  metadata.gz: e2274c749842a2824ffdb505efd67545f48aec77f6492d9f72b798c275ab4cdf88d8356e5464cf5e3c5f1c461a850de9e659b57e9c2d02d88118e90c35cf94c9
+  data.tar.gz: 1853d52571d2bf67d5563126b3317a270b00553edb34170fbf70a28da8c9c961d0cfe92825090a0b87dd7d311b968f41372a09e74d1379edc3fbd2fec2ccf349

data/lib/throttle_machines/storage/base.rb

@@ -57,8 +57,28 @@ module ThrottleMachines
         nil
       end
 
+      # Rounding slack for time comparisons, in units of the clock's precision.
+      # Matches the native core.
+      SLACK_ULPS = 64
+
       protected
 
+      # Times are running sums and differences of float seconds, so an
+      # on-schedule arrival can miss an exact boundary by a few ulps. The slack
+      # scales with the clock's magnitude.
+      def rounding_slack(time)
+        Float::EPSILON * SLACK_ULPS * [time.abs, 1.0].max
+      end
+
+      def gcra_allowed?(tat, now, delay_tolerance)
+        tat - now <= delay_tolerance + rounding_slack(tat)
+      end
+
+      # Whether a token is available, allowing for rounding in the refill.
+      def token_available?(tokens, now, refill_rate)
+        tokens >= 1 - (rounding_slack(now) * refill_rate)
+      end
+
       def current_time
         # Use monotonic time for consistency with BreakerMachines
         ThrottleMachines.monotonic_time

data/lib/throttle_machines/storage/memory.rb

@@ -86,7 +86,7 @@ module ThrottleMachines
           state = @gcra_states[key] || { tat: 0.0 }
 
           tat = [state[:tat], now].max
-          allow = tat - now <= delay_tolerance
+          allow = gcra_allowed?(tat, now, delay_tolerance)
 
           if allow
             new_tat = tat + emission_interval
@@ -107,7 +107,7 @@ module ThrottleMachines
           state = @gcra_states[key] || { tat: 0.0 }
 
           tat = [state[:tat], now].max
-          allow = tat - now <= delay_tolerance
+          allow = gcra_allowed?(tat, now, delay_tolerance)
 
           {
             allowed: allow,
@@ -130,8 +130,8 @@ module ThrottleMachines
           bucket[:last_refill] = now
 
           # Check if we can consume a token
-          if bucket[:tokens] >= 1
-            bucket[:tokens] -= 1
+          if token_available?(bucket[:tokens], now, refill_rate)
+            bucket[:tokens] = [bucket[:tokens] - 1, 0.0].max
             @token_buckets[key] = bucket.merge(expires_at: now + ttl)
 
             {
@@ -161,11 +161,11 @@ module ThrottleMachines
           tokens_to_add = elapsed * refill_rate
           current_tokens = [bucket[:tokens] + tokens_to_add, capacity].min
 
-          if current_tokens >= 1
+          if token_available?(current_tokens, now, refill_rate)
             {
               allowed: true,
               retry_after: 0,
-              tokens_remaining: (current_tokens - 1).floor
+              tokens_remaining: [current_tokens - 1, 0].max.floor
             }
           else
             retry_after = (1 - current_tokens) / refill_rate

data/lib/throttle_machines/storage/redis/gcra.lua

@@ -12,11 +12,15 @@ else
 end
 
 tat = math.max(tat, now)
-local allow = (tat - now) <= delay_tolerance
+-- The TAT is a running sum of emission intervals, so an on-schedule arrival
+-- can overshoot the tolerance by a few ulps; the slack scales with the clock.
+local slack = 2.220446049250313e-16 * 64 * math.max(math.abs(tat), 1)
+local allow = (tat - now) <= delay_tolerance + slack
 
 if allow then
   local new_tat = tat + emission_interval
   redis.call('SET', key, new_tat, 'EX', ttl)
 end
 
-return { allow and 1 or 0, tat }
+-- Redis truncates Lua numbers in replies to integers; send the TAT as text.
+return { allow and 1 or 0, string.format('%.17g', tat) }

data/lib/throttle_machines/storage/redis/peek_gcra.lua

@@ -11,6 +11,10 @@ else
 end
 
 tat = math.max(tat, now)
-local allow = (tat - now) <= delay_tolerance
+-- The TAT is a running sum of emission intervals, so an on-schedule arrival
+-- can overshoot the tolerance by a few ulps; the slack scales with the clock.
+local slack = 2.220446049250313e-16 * 64 * math.max(math.abs(tat), 1)
+local allow = (tat - now) <= delay_tolerance + slack
 
-return { allow and 1 or 0, tat }
+-- Redis truncates Lua numbers in replies to integers; send the TAT as text.
+return { allow and 1 or 0, string.format('%.17g', tat) }

data/lib/throttle_machines/storage/redis/peek_token_bucket.lua

@@ -12,7 +12,13 @@ local elapsed = now - last_refill
 local tokens_to_add = elapsed * refill_rate
 tokens = math.min(tokens + tokens_to_add, capacity)
 
-local allow = tokens >= 1
-local tokens_after = allow and (tokens - 1) or 0
+-- `elapsed` carries the clock's rounding; a token due exactly now may come
+-- out a hair short of 1. The slack scales with the clock, as in the native core.
+local slack = 2.220446049250313e-16 * 64 * math.max(math.abs(now), 1) * refill_rate
+local allow = tokens >= 1 - slack
+-- Admitted: tokens left after this request. Refused: the fractional balance,
+-- which retry_after is computed from.
+local tokens_after = allow and math.max(tokens - 1, 0) or tokens
 
-return { allow and 1 or 0, tokens_after }
+-- Redis truncates Lua numbers in replies to integers; send the count as text.
+return { allow and 1 or 0, string.format('%.17g', tokens_after) }

data/lib/throttle_machines/storage/redis/token_bucket.lua

@@ -13,11 +13,15 @@ local elapsed = now - last_refill
 local tokens_to_add = elapsed * refill_rate
 tokens = math.min(tokens + tokens_to_add, capacity)
 
-local allow = tokens >= 1
+-- `elapsed` carries the clock's rounding; a token due exactly now may come
+-- out a hair short of 1. The slack scales with the clock, as in the native core.
+local slack = 2.220446049250313e-16 * 64 * math.max(math.abs(now), 1) * refill_rate
+local allow = tokens >= 1 - slack
 if allow then
-  tokens = tokens - 1
+  tokens = math.max(tokens - 1, 0)
   redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
   redis.call('EXPIRE', key, ttl)
 end
 
-return { allow and 1 or 0, tokens }
+-- Redis truncates Lua numbers in replies to integers; send the count as text.
+return { allow and 1 or 0, string.format('%.17g', tokens) }

data/lib/throttle_machines/storage/redis.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'digest/sha1'
+
 module ThrottleMachines
   module Storage
     class Redis < Base
@@ -13,17 +15,18 @@ module ThrottleMachines
       INCREMENT_COUNTER_SCRIPT = File.read(File.join(LUA_SCRIPTS_DIR, 'increment_counter.lua'))
       # Breaker scripts removed: breaker state is owned by BreakerMachines
 
+      # Redis caches scripts by the SHA1 of their source, so the SHAs are known
+      # without a SCRIPT LOAD round trip.
+      GCRA_SHA = Digest::SHA1.hexdigest(GCRA_SCRIPT)
+      TOKEN_BUCKET_SHA = Digest::SHA1.hexdigest(TOKEN_BUCKET_SCRIPT)
+      PEEK_GCRA_SHA = Digest::SHA1.hexdigest(PEEK_GCRA_SCRIPT)
+      PEEK_TOKEN_BUCKET_SHA = Digest::SHA1.hexdigest(PEEK_TOKEN_BUCKET_SCRIPT)
+
       def initialize(options = {})
         super
         @redis = options[:redis] || options[:client] || options[:pool]
         @prefix = options[:prefix] || 'throttle:'
 
-        # Cache scripts to avoid repeated script loads
-        @gcra_sha = nil
-        @token_bucket_sha = nil
-        @peek_gcra_sha = nil
-        @peek_token_bucket_sha = nil
-
         # Validate Redis connection
         validate_redis_connection!
       end
@@ -56,111 +59,53 @@ module ThrottleMachines
 
       # GCRA operations (atomic via Lua)
       def check_gcra_limit(key, emission_interval, delay_tolerance, ttl)
-        ensure_gcra_script_loaded!
-
-        result = with_redis do |redis|
-          redis.evalsha(
-            @gcra_sha,
-            keys: [prefixed(key)],
-            argv: [emission_interval, delay_tolerance, ttl, current_time]
-          )
-        end
+        now = current_time
+        result = run_script(GCRA_SCRIPT, GCRA_SHA,
+                            keys: [prefixed(key)],
+                            argv: [emission_interval, delay_tolerance, ttl, now])
 
         allowed = result[0] == 1
-        tat = result[1]
-        now = current_time
+        tat = Float(result[1])
 
         {
           allowed: allowed,
           retry_after: allowed ? 0 : (tat - now - delay_tolerance),
           tat: tat
         }
-      rescue ::Redis::CommandError => e
-        raise unless e.message.include?('NOSCRIPT')
-
-        @gcra_sha = nil
-        retry
       end
 
       # Token bucket operations (atomic via Lua)
       def check_token_bucket(key, capacity, refill_rate, ttl)
-        ensure_token_bucket_script_loaded!
-
-        result = with_redis do |redis|
-          redis.evalsha(
-            @token_bucket_sha,
-            keys: [prefixed(key)],
-            argv: [capacity, refill_rate, ttl, current_time]
-          )
-        end
-
-        allowed = result[0] == 1
-        tokens = result[1]
+        result = run_script(TOKEN_BUCKET_SCRIPT, TOKEN_BUCKET_SHA,
+                            keys: [prefixed(key)],
+                            argv: [capacity, refill_rate, ttl, current_time])
 
-        {
-          allowed: allowed,
-          retry_after: allowed ? 0 : (1 - tokens) / refill_rate,
-          tokens_remaining: tokens.floor
-        }
-      rescue ::Redis::CommandError => e
-        raise unless e.message.include?('NOSCRIPT')
-
-        @token_bucket_sha = nil
-        retry
+        token_bucket_result(result, refill_rate)
       end
 
       # Peek methods for non-consuming checks
       def peek_gcra_limit(key, emission_interval, delay_tolerance)
-        ensure_peek_gcra_script_loaded!
-
-        result = with_redis do |redis|
-          redis.evalsha(
-            @peek_gcra_sha,
-            keys: [prefixed(key)],
-            argv: [emission_interval, delay_tolerance, current_time]
-          )
-        end
+        now = current_time
+        result = run_script(PEEK_GCRA_SCRIPT, PEEK_GCRA_SHA,
+                            keys: [prefixed(key)],
+                            argv: [emission_interval, delay_tolerance, now])
 
         allowed = result[0] == 1
-        tat = result[1]
-        now = current_time
+        tat = Float(result[1])
 
         {
           allowed: allowed,
           retry_after: allowed ? 0 : (tat - now - delay_tolerance),
           tat: tat
         }
-      rescue ::Redis::CommandError => e
-        raise unless e.message.include?('NOSCRIPT')
-
-        @peek_gcra_sha = nil
-        retry
       end
 
       def peek_token_bucket(key, capacity, refill_rate)
-        ensure_peek_token_bucket_script_loaded!
-
-        result = with_redis do |redis|
-          redis.evalsha(
-            @peek_token_bucket_sha,
-            keys: [prefixed(key)],
-            argv: [capacity, refill_rate, current_time]
-          )
-        end
+        result = run_script(PEEK_TOKEN_BUCKET_SCRIPT, PEEK_TOKEN_BUCKET_SHA,
+                            keys: [prefixed(key)],
+                            argv: [capacity, refill_rate, current_time])
 
-        allowed = result[0] == 1
-        tokens_remaining = result[1]
-
-        {
-          allowed: allowed,
-          retry_after: allowed ? 0 : (1 - tokens_remaining) / refill_rate,
-          tokens_remaining: tokens_remaining.floor
-        }
-      rescue ::Redis::CommandError => e
-        raise unless e.message.include?('NOSCRIPT')
-
-        @peek_token_bucket_sha = nil
-        retry
+        token_bucket_result(result, refill_rate)
       end
 
       # No circuit breaker operations: breaker state is owned by BreakerMachines
@@ -188,24 +133,34 @@ module ThrottleMachines
 
       private
 
-      def prefixed(key)
-        "#{@prefix}#{key}"
-      end
+      # `result` is [allowed, tokens]: the balance after an admission, or the
+      # fractional balance a refusal waits on. Matches Storage::Memory.
+      def token_bucket_result(result, refill_rate)
+        allowed = result[0] == 1
+        tokens = Float(result[1])
 
-      def ensure_gcra_script_loaded!
-        @ensure_gcra_script_loaded ||= with_redis { |r| r.script(:load, GCRA_SCRIPT) }
+        {
+          allowed: allowed,
+          retry_after: allowed ? 0 : (1 - tokens) / refill_rate,
+          tokens_remaining: allowed ? tokens.floor : 0
+        }
       end
 
-      def ensure_token_bucket_script_loaded!
-        @ensure_token_bucket_script_loaded ||= with_redis { |r| r.script(:load, TOKEN_BUCKET_SCRIPT) }
+      def prefixed(key)
+        "#{@prefix}#{key}"
       end
 
-      def ensure_peek_gcra_script_loaded!
-        @ensure_peek_gcra_script_loaded ||= with_redis { |r| r.script(:load, PEEK_GCRA_SCRIPT) }
-      end
+      # EVALSHA by the precomputed SHA. A server without the script cached (a
+      # restart, SCRIPT FLUSH, failover) answers NOSCRIPT; EVAL then runs the
+      # source once and caches it for later calls. Any other error propagates.
+      def run_script(script, sha, keys:, argv:)
+        with_redis do |redis|
+          redis.evalsha(sha, keys: keys, argv: argv)
+        rescue ::Redis::CommandError => e
+          raise unless e.message.include?('NOSCRIPT')
 
-      def ensure_peek_token_bucket_script_loaded!
-        @ensure_peek_token_bucket_script_loaded ||= with_redis { |r| r.script(:load, PEEK_TOKEN_BUCKET_SCRIPT) }
+          redis.eval(script, keys: keys, argv: argv)
+        end
       end
 
       def validate_redis_connection!

data/lib/throttle_machines/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ThrottleMachines
-  VERSION = '0.2.4'
+  VERSION = '0.3.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: throttle_machines
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.1
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: '8.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.0.4
+        version: '8.1'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -71,42 +71,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.19'
+        version: '0.20'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.19'
+        version: '0.20'
 - !ruby/object:Gem::Dependency
   name: chrono_machines
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.16'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.16'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: rb_sys
   requirement: !ruby/object:Gem::Requirement