redis-gcra 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1b80231f7f7cb343c629c565c27cf7b6d83cdef4
-  data.tar.gz: cdcce949d903b7da612eb466baf683fbb4479bf7
+  metadata.gz: '085c8c8eb0a8f54f613cec4551f777bf0ad3e49d'
+  data.tar.gz: fad812c225a86dd55234fd51e68911f6099f3c79
 SHA512:
-  metadata.gz: 275086f4ec7c050d699f61c35451cb01725adfc084de2bf813de97ae1df930a2dc39fb05ba137a4c34aca2197696e728636d38dee77e800f539f565a5779eda9
-  data.tar.gz: 33ed550d170ccb96ba70ff1d05a3add5655ec06fa2b3ba946444c2832f1470148d11b0208d4beb89a84dbaa57ca237fa0e63c77a3202694c6f23d8e04b860d83
+  metadata.gz: 8458a2915d214ea6f8c9daa247aa92ed25e46e61a42c4d274969970efd1fda3b7fa109f86afb4fcbe2c4bde1d6f6f1839ef0568324a1a56ca76010badcd79fb9
+  data.tar.gz: 75058e691d72f31eb6a147e157b112fd4968dff4d9897fae3a5a8bda6655c5adf44f51bfebedc5456e6fe8f6327ac8925f2a07fe6012eef623c5c8d120c13a41

data/README.md

@@ -2,10 +2,11 @@
 [![Build Status](https://travis-ci.org/rwz/redis-gcra.svg?branch=master)](https://travis-ci.org/rwz/redis-gcra)
 
 This gem is an implementation of GCRA for rate limiting based on Redis. The
-code requires Redis version 3.2+ or newer since it relies on
-[`replicate_comands`][redis-replicate-commands] feature.
+code requires Redis version 3.2 or newer since it relies on
+[`replicate_commands`][redis-replicate-commands] feature.
 
 [redis-replicate-commands]: https://redis.io/commands/eval#replicating-commands-instead-of-scripts
+
 ## Installation
 
 ```ruby
@@ -22,32 +23,67 @@ Or install it yourself as:
 
 ## Usage
 
+In order to perform rate limiting, you need to call the `limit` method.
+
+In this example the rate limit bucket has 1000 tokens in it and recovers at
+speed of 100 tokens per minute.
+
 ```ruby
 redis = Redis.new
 
 result = RedisGCRA.limit(
   redis: redis,
-  key: "rate-limit-key",
+  key: "overall-account/bob@example.com",
   burst: 1000,
   rate: 100,
-  period: 60,
+  period: 60, # seconds
   cost: 2
 )
 
 result.limited?    # => false - request should not be limited
 result.remaning    # => 998   - remaining number of requests until limited
 result.retry_after # => nil   - can retry without delay
-result.reset_after # => ~0.6  - in 0.6s rate limiter will completely reset
+result.reset_after # => ~0.6  - in 0.6 seconds rate limiter will completely reset
 
-# do this 500 more times and then
+# call limit 499 more times in rapid succession and you get:
 
 result.limited?    # => true - request should be limited
 result.remaining   # => 0    - no requests can be made at this point
-result.retry_after # => ~1.1 - can retry in 1.1seconds
-result.reset_after # => ~600 - in 600s rate limiter will completely reset
+result.retry_after # => ~1.1 - can retry in 1.1 seconds
+result.reset_after # => ~600 - in 600 seconds rate limiter will completely reset
+```
+
+The implementation utilizes single key in Redis that matches the key you pass
+to the `limit` method. If you need to reset rate limiter for particular key,
+just delete the key from Redis:
+
+```ruby
+# Let's imagine `overall-account/bob@example.com` is limited.
+# This will effectively reset limit for the key:
+redis.del "overall-account/bob@example.com"
+```
+
+You call also retrieve the current state of rate limiter for particular key
+without actually modifying the state. Of order to do that, use the `peek`
+method:
+
+```ruby
+RedisGCRA.peek(
+  redis: redis,
+  key: "overall-account/bob@example.com",
+  burst: 1000,
+  rate: 100,
+  period: 60 # seconds
+)
+
+result.limited?    # => true - current state is limited
+result.remaining   # => 0    - no requests can be made
+result.retry_after # => nil  - peek always return nil here
+result.reset_after # => ~600 - in 600 seconds rate limiter will completely reset
 ```
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT
+License](http://opensource.org/licenses/MIT).
 

data/lib/redis-gcra.rb

@@ -6,22 +6,29 @@ module RedisGCRA
   autoload :Result, "redis-gcra/result"
 
   def limit(redis:, key:, burst:, rate:, period:, cost: 1)
-    resp = call_script(
-      redis,
-      :perform_gcra_ratelimit,
-      keys: [key],
-      argv: [burst, rate, period, cost]
-    )
+    call redis, :perform_gcra_ratelimit, key, burst, rate, period, cost
+  end
+
+  def peek(redis:, key:, burst:, rate:, period:)
+    call redis, :inspect_gcra_ratelimit, key, burst, rate, period
+  end
+
+  private
+
+  def call(redis, script_name, key, *argv)
+    res = call_script(redis, script_name, keys: [key], argv: argv)
 
     Result.new(
-      limited: resp[0] == 1,
-      remaining: resp[1],
-      retry_after: resp[2] == "-1" ? nil : resp[2].to_f,
-      reset_after: resp[3].to_f
+      limited: res[0] == 1,
+      remaining: res[1],
+      retry_after: parse_float_string(res[2]),
+      reset_after: parse_float_string(res[3])
     )
   end
 
-  private
+  def parse_float_string(value)
+    value == "-1" ? nil : value.to_f
+  end
 
   def call_script(redis, script_name, *args)
     script_sha = mutex.synchronize { get_cached_sha(redis, script_name) }
@@ -37,13 +44,12 @@ module RedisGCRA
   end
 
   def get_cached_sha(redis, script_name)
-    sha = redis_cache.dig(redis.id, script_name)
-    return sha if sha
-
-    script = File.read(File.expand_path("../../vendor/#{script_name}.lua", __FILE__))
-    sha = redis.script(:load, script)
-    redis_cache[redis.id] ||= {}
-    redis_cache[redis.id][script_name] = sha
-    sha
+    cache_key = "#{redis.id}/#{script_name}"
+    redis_cache[cache_key] ||= load_script(redis, script_name)
+  end
+
+  def load_script(redis, script_name)
+    script_path = File.expand_path("../../vendor/#{script_name}.lua", __FILE__)
+    redis.script(:load, File.read(script_path))
   end
 end

data/lib/redis-gcra/version.rb

@@ -1,3 +1,3 @@
 module RedisGCRA
-  VERSION = "0.1.0".freeze
+  VERSION = "0.2.0".freeze
 end

data/vendor/inspect_gcra_ratelimit.lua

@@ -0,0 +1,45 @@
+local rate_limit_key = KEYS[1]
+local burst = ARGV[1]
+local rate = ARGV[2]
+local period = ARGV[3]
+
+local emission_interval = period / rate
+local burst_offset = emission_interval * burst
+local now = redis.call("TIME")
+
+-- redis returns time as an array containing two integers: seconds of the epoch
+-- time and microseconds. for convenience we need to convert them to float
+-- point number
+now = now[1] + now[2] / 1000000
+
+local tat = redis.call("GET", rate_limit_key)
+
+if not tat then
+  tat = now
+else
+  tat = tonumber(tat)
+end
+
+local allow_at = math.max(tat, now) - burst_offset
+local diff = now - allow_at
+
+local remaining = math.floor(diff / emission_interval)
+
+local reset_after = tat - now
+if reset_after == 0 then
+  reset_after = -1
+end
+
+local limited
+
+if remaining == 0 then
+  limited = 1
+else
+  limited = 0
+end
+
+-- retry_after is always nil because it doesn't make much sense in inspect
+-- context
+local retry_after = -1
+
+return {limited, remaining, tostring(retry_after), tostring(reset_after)}

data/vendor/perform_gcra_ratelimit.lua

@@ -41,13 +41,11 @@ if diff < 0 then
   reset_after = tat - now
   retry_after = diff * -1
 else
-  local ttl = new_tat - now
-  redis.call("SET", rate_limit_key, new_tat, "EX", math.ceil(ttl))
-  local next_in = burst_offset - ttl
-  remaining = math.floor(next_in / emission_interval)
-  reset_after = ttl
-  retry_after = -1
   limited = 0
+  reset_after = new_tat - now
+  redis.call("SET", rate_limit_key, new_tat, "EX", math.ceil(reset_after))
+  remaining = math.floor(diff / emission_interval)
+  retry_after = -1
 end
 
 return {limited, remaining, tostring(retry_after), tostring(reset_after)}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis-gcra
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Pavel Pravosud
@@ -36,6 +36,7 @@ files:
 - lib/redis-gcra.rb
 - lib/redis-gcra/result.rb
 - lib/redis-gcra/version.rb
+- vendor/inspect_gcra_ratelimit.lua
 - vendor/perform_gcra_ratelimit.lua
 homepage: https://github.com/rwz/redis-gcra
 licenses: