ihasa 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 46f87a6594af9e83c6ff6d56f7d897d376325993
+  data.tar.gz: 13437815218c853f71cae4a93b0af469bfaee9bb
+SHA512:
+  metadata.gz: dd880e51552ae7a23d07b7f6ea93e1cd333e3ee82bdeed6ea207c343deb71e026c9ddb4caa2c24e68e3993f879e37444117523927c887d85f78a2cc7e9e42c5b
+  data.tar.gz: 9316733742bf6224bc8bf137ab804970530a69e6be3bb66e19361812fdfa21dd5afe3a7de69f2c8b3a91e4e44c3f04ff685675677805e1869311329a3706321d

data/Gemfile.lock

@@ -0,0 +1,44 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.2.0)
+    byebug (8.2.2)
+    diff-lcs (1.2.5)
+    parser (2.3.1.0)
+      ast (~> 2.2)
+    powerpack (0.1.1)
+    rainbow (2.1.0)
+    redis (3.3.0)
+    rspec (3.4.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+    rspec-core (3.4.4)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.1)
+    rubocop (0.40.0)
+      parser (>= 2.3.1.0, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.8.1)
+    unicode-display_width (1.0.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  byebug
+  redis
+  rspec
+  rubocop
+
+BUNDLED WITH
+   1.11.2

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012-14 Bozhidar Batsov
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,139 @@
+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?*
+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)
+
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Advanced](#advanced)
+- [Example](#example)
+
+## Installation
+
+Installation is standard:
+
+```
+$ gem install ihasa
+```
+
+You can as well include it in you `Gemfile`:
+
+```
+gem 'rubocop', require: false
+```
+
+## Usage
+
+Be sure to require Ihasa:
+
+```ruby
+require 'ihasa'
+```
+
+To create a new bucket accepting 5 requests per second with an allowed burst of 10
+requests per second (the default values), use the `Ihasa.bucket` method:
+
+```ruby
+bucket = Ihasa.bucket
+```
+
+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:
+
+```ruby
+def process(request)
+  if @bucket.accept?
+    # Do very interesting things with the request
+    # ...
+  else
+    puts "Could not process request #{request}. Rate limit violated."
+  end
+end
+```
+
+Please note that there is also a `Ihasa::Bucket#accept?!` method that raise a
+`Ihasa::Bucket::EmptyBucket` errors if the limit is violated.
+
+### Advanced
+
+Here is some details on the available configuration options of the Ihasa::Bucket
+class.
+
+#### Configuring rate and burst limit
+
+Two configuration options exists to configure the rate and burst limits:
+
+```ruby
+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
+configure different namespace for each of them.
+
+Here is an example of using two different buckets for reading and writing to data:
+
+```ruby
+class Controller < ActionController::Base
+  def self.read_bucket
+    @read_bucket ||= Ihasa.bucket(prefix: 'read')
+  end
+
+  def self.write_bucket
+    @write_bucket ||= Ihasa.bucket(prefix: 'write')
+  end
+
+  def read(request)
+    return head 403 unless self.class.read_bucket.accept?
+    # ... Standard rendering ...
+  end
+
+  def write(request)
+    return head 403 unless self.class.write_bucket.accept?
+    # ... Standard rendering ...
+  end
+```
+
+#### 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:
+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:
+
+```ruby
+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:
+
+```ruby
+class RateLimiter
+  BUCKET = Ihasa.bucket(rate: 20, burst: 100)
+
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    return @app.call(env) if BUCKET.accept?
+    [403, {'Content-Type' => 'text/plain'}, ["Request limit violated\n"]]
+  end
+end
+```

data/ihasa.gemspec

@@ -0,0 +1,44 @@
+# encoding: utf-8
+
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'ihasa/version'
+
+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.authors = ['Alexandre Ignjatovic']
+  s.description = <<-EOF
+    A Redis-backed rate limiter written in ruby and
+    using the token bucket algorithm.
+    Its light and efficient implementation takes
+    advantage of the Lua capabilities of Redis.
+  EOF
+
+  s.email = 'alexandre.ignjatovic@gmail.com'
+  s.files = `git ls-files`.split($RS).reject do |file|
+    file =~ %r{^(?:
+    spec/.*
+    |Gemfile
+    |Rakefile
+    |\.rspec
+    |\.gitignore
+    |\.rubocop.yml
+    |\.rubocop_todo.yml
+    |.*\.eps
+    )$}x
+  end
+  s.test_files = []
+  s.executables = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  s.extra_rdoc_files = ['LICENSE.txt', 'README.md']
+  s.homepage = 'http://github.com/bankair/ihasa'
+  s.licenses = ['MIT']
+  s.require_paths = ['lib']
+  s.rubygems_version = '1.8.23'
+
+  s.summary = 'Redis-backed rate limiter (token bucket) written in Ruby and Lua'
+
+  s.add_runtime_dependency('redis', '~> 3')
+  s.add_development_dependency('rspec', '~> 3.4')
+end

data/lib/ihasa.rb

@@ -0,0 +1,19 @@
+require 'redis'
+require 'ihasa/version'
+require 'ihasa/bucket'
+
+module Ihasa
+  module_function
+  def default_redis
+    @redis ||= if ENV['REDIS_URL']
+                 Redis.new url: ENV['REDIS_URL']
+               else
+                 Redis.new
+               end
+  end
+
+  DEFAULT_REDIS_PREFIX = 'IHAB'
+  def bucket(rate: 5, burst: 10, prefix: DEFAULT_REDIS_PREFIX, redis: default_redis)
+    @implementation = Bucket.new(rate, burst, prefix, redis)
+  end
+end

data/lib/ihasa/bucket.rb

@@ -0,0 +1,123 @@
+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
+    def initialize(rate, burst, prefix, redis)
+      @prefix = prefix
+      @keys = {}
+      @keys[:rate] = "#{prefix}:RATE"
+      @keys[:allowance] = "#{prefix}:ALLOWANCE"
+      @keys[:burst] = "#{prefix}:BURST"
+      @keys[:last] = "#{prefix}:LAST"
+      @redis = redis
+      @rate = Float rate
+      @burst = Float burst
+      redis_init
+    end
+
+    def accept?
+      result = redis_eval(statement) == OK
+      return yield if result && block_given?
+      result
+    end
+
+    class EmptyBucket < RuntimeError; end
+
+    def accept!
+      result = (block_given? ? accept?(&Proc.new) : accept?)
+      raise EmptyBucket, "Bucket #{@prefix} throttle limit" unless result
+      result
+    end
+
+    protected
+
+    def redis_init
+      redis_eval <<-LUA
+        #{INTRO_STATEMENT}
+        #{redis_set rate, @rate}
+        #{redis_set burst, @burst}
+        #{redis_set allowance, @burst}
+        #{redis_set last, 'now'}
+      LUA
+    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
+          #{redis_set(last, 'now')}
+          allowance = allowance - 1.0
+          result = #{OK}
+        end
+        #{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}))"
+    end
+
+    def method_missing(sym, *args, &block)
+      super unless @keys.key?(sym)
+      redis_key sym
+    end
+  end
+end

data/lib/ihasa/version.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+module Ihasa
+  # This module holds the Ihasa version information.
+  module Version
+    STRING = '0.0.1'
+
+    module_function
+
+    def version(debug = false)
+      STRING
+    end
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: ihasa
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Alexandre Ignjatovic
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-05-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+description: |2
+      A Redis-backed rate limiter written in ruby and
+      using the token bucket algorithm.
+      Its light and efficient implementation takes
+      advantage of the Lua capabilities of Redis.
+email: alexandre.ignjatovic@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- ihasa.gemspec
+- lib/ihasa.rb
+- lib/ihasa/bucket.rb
+- lib/ihasa/version.rb
+homepage: http://github.com/bankair/ihasa
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Redis-backed rate limiter (token bucket) written in Ruby and Lua
+test_files: []