ihasa 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 54a2fc759ca9910bc5e2153bde55d374dc3ef2bb
-  data.tar.gz: 001131036b26d03947150db2f2ed61e63f2d8a1a
+  metadata.gz: bb33afd1cc7c68a0cbcbaba333ded91ad08eca2b
+  data.tar.gz: 63972017da74a9b3f2ee8de0e5644ef01cfdd6aa
 SHA512:
-  metadata.gz: cfe56b58bd987f45f5b2a0214871ae637214f8d4a590e6b2ad2563c87ca0619c0dfb219896c59b5e0f1774c5577a4588f406827978ae6f52ee963eb59d14e68b
-  data.tar.gz: 9341610417ed54fbd1c0b488031ff83140972e82fc4d9ba029fd92f184e143810b5fefd9375880ad4441ef1f29eca8d68c625db8e4f9d9fd3155e5846a432e14
+  metadata.gz: 1a32eabe6c7d6c0ff132dbb48e385ba5f8c8c928feacdb1c7ca0fcb313d918da4f8b1de65dc9ef6f4adeeea20cbeebdab2f9ff8fe20fe06f9fe7b89b3c936f39
+  data.tar.gz: 50ff73af381171104c20922562de2fcaa2f8273e0ba3bf638d656c18b58502b1870858784556b7a769dfdf326662c8c4c377ebc40f8c38077bef917f6882252c

data/.ruby-version

@@ -0,0 +1 @@
+2.3.1

data/.travis.yml

@@ -0,0 +1,3 @@
+script: bundle exec rspec
+services:
+  - redis-server

data/README.md

@@ -1,16 +1,21 @@
-No more pounding on your APIs !
+# Ihasa
+
+[![Build Status](https://travis-ci.org/bankair/ihasa.svg?branch=master)](https://travis-ci.org/bankair/ihasa)
+
+_No more pounding on your APIs !_
 
 Ihasa is a ruby implementation of the [token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket) backed-up by Redis.
 
 It  provides a way to share your rate/burst limit across multiple servers, as well as a simple interface.
 
-*Why use Ihasa?*
+**Why use Ihasa?**
 
-1. It's easy to use ([go check the usage section](#usage)
+1. It's easy to use ([go check the usage section](#usage))
 2. It supports rate AND burst
 3. It does not reset all rate limit consumption each new second/minute/hour
 4. It has [namespaces](#namespaces)
 
+This README file contains the following sections:
 
 - [Installation](#installation)
 - [Usage](#usage)
@@ -25,7 +30,7 @@ Installation is standard:
 $ gem install ihasa
 ```
 
-You can as well include it in you `Gemfile`:
+You can include it in your `Gemfile` as well:
 
 ```
 gem 'ihasa', require: false
@@ -39,7 +44,7 @@ Be sure to require Ihasa:
 require 'ihasa'
 ```
 
-To create a new bucket accepting 5 requests per second with an allowed burst of 10
+To create a new bucket that accepts 5 requests per second with an allowed burst of 10
 requests per second (the default values), use the `Ihasa.bucket` method:
 
 ```ruby
@@ -50,8 +55,8 @@ Please note that the default redis connection is built from the `REDIS_URL`
 environment variable, or use the default constructor of redis-rb
 (`redis://localhost:6379`).
 
-Now, you can use your token bucket to check if an incoming request can be handled
-or must be turned down:
+Now, you can use your token bucket to check if an incoming request can be handled,
+or must be declined:
 
 ```ruby
 def process(request)
@@ -64,22 +69,24 @@ def process(request)
 end
 ```
 
-Please note that there is also a `Ihasa::Bucket#accept?!` method that raise a
-`Ihasa::Bucket::EmptyBucket` errors if the limit is violated.
+Please note that there is also a `Ihasa::Bucket#accept?!` method that raises an
+`Ihasa::Bucket::EmptyBucket` error if the limit has already been reached.
 
 ### Advanced
 
 In this section, you will find some details on the available configuration options of the Ihasa::Bucket
-class, as well a some advices to run lots of Bucket simultaneously.
+class, as well as advice on how to run many Buckets simultaneously.
 
-#### Using a lots of different buckets
+#### Using multiple buckets
 
-If you want to enforce rate limits by customer, you have to create as many buckets as customers you have.
-Which can be a lot if you are successful ;).
+If you want to enforce per-customer rate limits, you must create as many buckets as you have customers.
+Which can be quite a few if you are successful ;).
 
-To have a lots of buckets in parallel and to avoid resetting your redis namespaces too often, I suggest you
-no longer use the `Ihasa.bucket` method. Instead, you should back-up your buckets with activerecord models
-(for example) and initialize them in a callback runned after the models creation.
+To have many buckets in parallel, and to avoid resetting your redis namespaces too often, I suggest you
+no longer use the `Ihasa.bucket` method. Instead, you should back up your buckets with activerecord models
+(for example) and initialize them in an after-creation model callback.
+
+To help you with that, we added the `save` and `delete` instance methods to the `Ihasa::Bucket` class.
 
 Example:
 
@@ -91,10 +98,14 @@ Example:
       @implementation ||= Ihasa::Bucket.new(rate, burst, prefix, $redis)
     end
 
-    # The Ihasa::Bucket#initialize_redis_namespace set the relevant
+    # The Ihasa::Bucket#save set the relevant
     # keys in your redis instance to have a working bucket. Do it
     # only when you create or update your bucket's configuration.
-    after_save { implementation.initialize_redis_namespace }
+    after_save { implementation.save }
+
+    # The Ihasa::Bucket#delete remove the variables stored into
+    # the redis instance.
+    after_destroy { implementation.delete }
 
     delegate :accept?, to: :implementation
   end
@@ -124,9 +135,9 @@ Example:
   end
 ```
 
-#### Configuring rate and burst limit
+#### Configuring rate limit and burst limit
 
-Two configuration options exists to configure the rate and burst limits:
+You can configure both the rate limit and burst limit:
 
 ```ruby
 bucket = Ihasa.bucket(rate: 20, burst: 100)
@@ -134,7 +145,7 @@ bucket = Ihasa.bucket(rate: 20, burst: 100)
 
 #### Namespaces
 
-You can have as many bucket as you want on the same redis instance, as long as you
+You can have as many buckets as you want on the same redis instance, as long as you
 configure different namespace for each of them.
 
 Here is an example of using two different buckets for reading and writing to data:
@@ -162,11 +173,11 @@ class Controller < ActionController::Base
 
 #### Redis
 
-By default, all new buckets use the redis instance hosted at localhost:6379. There is
-however two way to configure the used redis instance:
+By default, all new buckets use the redis instance hosted at localhost:6379. You can
+override this default like so:
 
 1. Override the `REDIS_URL` env variable. All new buckets will use that instance
-2. Override the redis url on a bucket creation basis like follow:
+2. Override the redis url on a bucket creation basis like this:
 
 ```ruby
 Ihasa.bucket(redis: Redis.new(url: 'redis://fancy_host:6379'))
@@ -174,8 +185,8 @@ Ihasa.bucket(redis: Redis.new(url: 'redis://fancy_host:6379'))
 
 ## Example
 
-This is an example of a rack middleware accepting 20 requests per seconds, and
-tolerating burst up to 100 requests per second:
+This is an example of a rack middleware that accepts 20 requests per seconds, and
+allows bursts up to 100 requests per second:
 
 ```ruby
 class RateLimiter

data/ihasa.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.name = 'ihasa'
   s.version = Ihasa::Version::STRING
   s.platform = Gem::Platform::RUBY
-  s.required_ruby_version = '>= 1.9.3'
+  s.required_ruby_version = '>= 2.0.0'
   s.authors = ['Alexandre Ignjatovic']
   s.description = <<-EOF
     A Redis-backed rate limiter written in ruby and

data/lib/ihasa.rb

@@ -1,9 +1,14 @@
 require 'redis'
 require 'ihasa/version'
-require 'ihasa/bucket'
 
 # Ihasa module. Root of the Ihasa::Bucket class
 module Ihasa
+  NOK = 0
+  OK = 1
+  OPTIONS = %i(rate burst last allowance).freeze
+
+  require 'ihasa/bucket'
+
   module_function
 
   def default_redis
@@ -16,6 +21,6 @@ module Ihasa
 
   DEFAULT_PREFIX = 'IHAB'.freeze
   def bucket(rate: 5, burst: 10, prefix: DEFAULT_PREFIX, redis: default_redis)
-    Bucket.new(rate, burst, prefix, redis).tap(&:initialize_redis_namespace)
+    Bucket.create(rate, burst, prefix, redis)
   end
 end

data/lib/ihasa/bucket.rb

@@ -1,31 +1,50 @@
-require 'digest/sha1'
+require 'ihasa/lua'
 module Ihasa
-  NOK = 0
-  OK = 1
   # Bucket class. That bucket fills up to burst, by rate per
   # second. Each accept? or accept?! call decrement it from 1.
   class Bucket
-    attr_reader :redis
+    class << self
+      def create(*args)
+        new(*args).tap(&:save)
+      end
+
+      REDIS_VERSION_WITH_REPLICATE_COMMANDS_SUPPORT = 3.2
+
+      def legacy_mode?(redis)
+        redis_version(redis) < REDIS_VERSION_WITH_REPLICATE_COMMANDS_SUPPORT
+      end
+
+      private
+
+      def redis_version(redis)
+        Float(redis.info['redis_version'][/\d+\.\d+/])
+      end
+    end
+
+    attr_reader :redis, :keys, :rate, :burst, :prefix
     def initialize(rate, burst, prefix, redis)
+      @implementation =
+        if self.class.legacy_mode?(redis)
+          require 'ihasa/bucket/legacy_implementation'
+          LegacyImplementation.instance
+        else
+          require 'ihasa/bucket/implementation'
+          Implementation.instance
+        end
       @prefix = prefix
-      @keys = {}
-      @keys[:rate] = "#{prefix}:RATE"
-      @keys[:allowance] = "#{prefix}:ALLOWANCE"
-      @keys[:burst] = "#{prefix}:BURST"
-      @keys[:last] = "#{prefix}:LAST"
+      @keys = Ihasa::OPTIONS.map { |opt| "#{prefix}:#{opt.upcase}" }
       @redis = redis
       @rate = Float rate
       @burst = Float burst
-      self.digest = Digest::SHA1.hexdigest statement
     end
 
     SETUP_ADVICE = 'Ensure that the method '\
-    'Ihasa::Bucket#initialize_redis_namespace was called.'.freeze
+      'Ihasa::Bucket#save was called.'.freeze
     SETUP_ERROR = ('Redis raised an error: %{msg}. ' + SETUP_ADVICE).freeze
     class RedisNamespaceSetupError < RuntimeError; end
 
     def accept?
-      result = redis.evalsha(digest, redis_keys) == OK
+      result = @implementation.accept?(self) == OK
       return yield if result && block_given?
       result
     rescue Redis::CommandError => e
@@ -36,106 +55,16 @@ module Ihasa
 
     def accept!
       result = (block_given? ? accept?(&Proc.new) : accept?)
-      raise EmptyBucket, "Bucket #{@prefix} throttle limit" unless result
+      raise EmptyBucket, "Bucket #{prefix} throttle limit" unless result
       result
     end
 
-    def initialize_redis_namespace
-      load_statement
-      redis_eval <<-LUA
-        #{INTRO_STATEMENT}
-        #{redis_set rate, @rate}
-        #{redis_set burst, @burst}
-        #{redis_set allowance, @burst}
-        #{redis_set last, 'now'}
-      LUA
-    end
-
-    protected
-
-    attr_accessor :digest
-
-    def load_statement
-      sha = redis.script(:load, statement)
-      if sha != digest
-        raise 'SHA1 inconsistency: expected #{digest}, got #{sha}'
-      end
-    end
-
-    require 'forwardable'
-    extend Forwardable
-
-    def_delegator :@keys, :keys
-    def_delegator :@keys, :values, :redis_keys
-
-    def index(key)
-      keys.index(key) + 1
-    end
-
-    # Please note that the replicate_commands is mandatory when using a
-    # non deterministic command before writing shit to the redis instance.
-    INTRO_STATEMENT = <<-LUA.freeze
-      redis.replicate_commands()
-      local now = redis.call('TIME')
-      now = now[1] + now[2] * 10 ^ -6
-    LUA
-
-    def redis_eval(statement)
-      redis.eval(statement, redis_keys)
-    end
-
-    ELAPSED_STATEMENT = 'local elapsed = now - last'.freeze
-
-    def local_statements
-      results = %i(rate burst last allowance).map do |key|
-        "local #{key} = tonumber(#{redis_get(redis_key(key))})"
-      end
-      results << ELAPSED_STATEMENT
-      results.join "\n"
-    end
-
-    ALLOWANCE_UPDATE_STATEMENT = <<-LUA.freeze
-      allowance = allowance + (elapsed * rate)
-      if allowance > burst then
-        allowance = burst
-      end
-    LUA
-
-    def statement
-      @statement ||= <<-LUA
-        #{INTRO_STATEMENT}
-        #{local_statements}
-        #{ALLOWANCE_UPDATE_STATEMENT}
-        local result = #{NOK}
-        if allowance >= 1.0 then
-          allowance = allowance - 1.0
-          result = #{OK}
-        end
-        #{redis_set(last, 'now')}
-        #{redis_set(allowance, 'allowance')}
-        return result
-      LUA
-    end
-
-    def redis_exists(key)
-      "redis.call('EXISTS', #{key})"
-    end
-
-    def redis_key(key)
-      "KEYS[#{index key}]"
-    end
-
-    def redis_get(key)
-      "tonumber(redis.call('GET', #{key}))"
-    end
-
-    def redis_set(key, value)
-      "redis.call('SET', #{key}, tostring(#{value}))"
+    def save
+      @implementation.save(self)
     end
 
-    def method_missing(sym, *args, &block)
-      super unless @keys.key?(sym)
-      redis_key sym
+    def delete
+      redis.del(keys)
     end
   end
 end

data/lib/ihasa/bucket/implementation.rb

@@ -0,0 +1,23 @@
+require 'ihasa/lua'
+require 'singleton'
+module Ihasa
+  # For redis server whith version >= 3.2
+  class Bucket::Implementation
+    include Singleton
+
+    def save(bucket)
+      sha = bucket.redis.script(:load, Lua::TOKEN_BUCKET_ALGORITHM)
+      if sha != Lua::TOKEN_BUCKET_HASH
+        raise "SHA1 mismatch: expected #{Lua::TOKEN_BUCKET_HASH}, got #{sha}"
+      end
+      bucket.redis.eval(
+        Lua.configuration(bucket.rate, bucket.burst),
+        bucket.keys
+      )
+    end
+
+    def accept?(bucket)
+      bucket.redis.evalsha(Lua::TOKEN_BUCKET_HASH, bucket.keys)
+    end
+  end
+end

data/lib/ihasa/bucket/legacy_implementation.rb

@@ -0,0 +1,33 @@
+require 'ihasa/lua'
+require 'singleton'
+module Ihasa
+  # For redis server whose version is prior to 3.2
+  class Bucket::LegacyImplementation
+    include Singleton
+
+    def save(bucket)
+      bucket.redis.eval(
+        Lua.configuration(
+          bucket.rate,
+          bucket.burst,
+          Lua.now_declaration(redis_time(bucket.redis))
+        ),
+        bucket.keys
+      )
+    end
+
+    def accept?(bucket)
+      now = redis_time bucket.redis
+      script = Lua.token_bucket_algorithm_legacy(now)
+      bucket.redis.eval(script, bucket.keys)
+    end
+
+    private
+
+    MICROSECS_PER_SEC = 10**6
+    def redis_time(redis)
+      seconds, microseconds = redis.time
+      seconds + microseconds.to_f / MICROSECS_PER_SEC
+    end
+  end
+end

data/lib/ihasa/lua.rb

@@ -0,0 +1,99 @@
+require 'digest/sha1'
+module Ihasa
+  # Contains lua related logic
+  module Lua
+    NOW_DECLARATION = <<-LUA.freeze
+      redis.replicate_commands()
+      local now = redis.call('TIME')
+      now = now[1] + now[2] * 10 ^ -6
+    LUA
+
+    ALLOWANCE_UPDATE_STATEMENT = <<-LUA.freeze
+      allowance = allowance + (elapsed * rate)
+      if allowance > burst then
+        allowance = burst
+      end
+    LUA
+
+    class << self
+      def now_declaration(value)
+        "local now = #{value}"
+      end
+
+      # Please note that the replicate_commands is mandatory when using a
+      # non deterministic command before writing shit to the redis instance
+      # for versions >= 3.2
+      def configuration(rate_value, burst_value, now_declaration = NOW_DECLARATION)
+        <<-LUA
+          #{now_declaration}
+          #{set rate, rate_value}
+          #{set burst, burst_value}
+          #{set allowance, burst_value}
+          #{set last, 'now'}
+        LUA
+      end
+
+      def index(key)
+        Integer(Ihasa::OPTIONS.index(key)) + 1
+      end
+
+      def fetch(key)
+        "KEYS[#{index key}]"
+      end
+
+      def get(key)
+        "tonumber(redis.call('GET', #{key}))"
+      end
+
+      def set(key, value)
+        "redis.call('SET', #{key}, tostring(#{value}))"
+      end
+
+      def exists?(key)
+        "redis.call('EXISTS', #{key})"
+      end
+
+      def method_missing(sym, *args, &block)
+        super unless Ihasa::OPTIONS.include? sym
+        fetch sym
+      end
+
+      def to_local(key)
+        "local #{key} = tonumber(#{get(fetch(key))})"
+      end
+      
+      def token_bucket_algorithm_legacy(now_value)
+        <<-LUA.freeze
+          #{now_declaration(now_value)}
+          #{TOKEN_BUCKET_ALGORITHM_BODY}
+        LUA
+      end
+    end
+
+    ELAPSED_STATEMENT = 'local elapsed = now - last'.freeze
+    SEP = "\n".freeze
+    LOCAL_VARIABLES = Ihasa::OPTIONS
+                      .map { |key| to_local(key) }
+                      .tap { |vars| vars << ELAPSED_STATEMENT }.join(SEP).freeze
+    TOKEN_BUCKET_ALGORITHM_BODY = <<-LUA.freeze
+      #{LOCAL_VARIABLES}
+      #{ALLOWANCE_UPDATE_STATEMENT}
+      local result = #{Ihasa::NOK}
+      if allowance >= 1.0 then
+        allowance = allowance - 1.0
+        result = #{Ihasa::OK}
+      end
+      #{set(last, 'now')}
+      #{set(allowance, 'allowance')}
+      return result
+    LUA
+    TOKEN_BUCKET_ALGORITHM = <<-LUA.freeze
+      #{NOW_DECLARATION}
+      #{TOKEN_BUCKET_ALGORITHM_BODY}
+    LUA
+    TOKEN_BUCKET_HASH = Digest::SHA1.hexdigest(
+      Lua::TOKEN_BUCKET_ALGORITHM
+    ).freeze
+
+  end
+end

data/lib/ihasa/version.rb

@@ -3,7 +3,7 @@
 module Ihasa
   # This module holds the Ihasa version information.
   module Version
-    STRING = '1.0.0'
+    STRING = '1.1.0'
 
     module_function
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ihasa
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Alexandre Ignjatovic
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-21 00:00:00.000000000 Z
+date: 2016-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -50,12 +50,17 @@ extra_rdoc_files:
 - LICENSE.txt
 - README.md
 files:
+- ".ruby-version"
+- ".travis.yml"
 - Gemfile.lock
 - LICENSE.txt
 - README.md
 - ihasa.gemspec
 - lib/ihasa.rb
 - lib/ihasa/bucket.rb
+- lib/ihasa/bucket/implementation.rb
+- lib/ihasa/bucket/legacy_implementation.rb
+- lib/ihasa/lua.rb
 - lib/ihasa/version.rb
 homepage: http://github.com/bankair/ihasa
 licenses:
@@ -69,7 +74,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.9.3
+      version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="