simple_throttle 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c5d75f7ea1ae6ba61f7ec9894e4247259d3195f8
+  data.tar.gz: b1cb14758b9d5729ab9cae5baa22c8cbd40eb9b1
+SHA512:
+  metadata.gz: 78c8fd5675425a14094a04ff7f745a8da481d51741da8605ff3f460d77160b6421b30ae6ebba9bb412c45a28a0df8bc502c4a2dd19bd4cf8f87056ba753dcee3
+  data.tar.gz: 3553b9f03f048bb96b83935ff93fede2c034d83e9656d32e314e9c8cacec8bf681715c593663e4ce357ba41c59d075b153ecce581af853755c1479565c1a386d

data/MIT_LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2016 WHI, Inc.
+
+MIT License
+
+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,24 @@
+This gem provides a very simple throttling mechanism backed by redis for limiting access to a resource.
+
+## Usage
+
+```ruby
+# Initialize Redis client
+SimpleThrottle.set_redis(Redis.new)
+
+# Add a global throttle (max of 10 requests in 60 seconds)
+SimpleThrottle.add(:things, limit: 10, ttl: 60)
+
+# Throttle a resource
+if SimpleThrottle[:things].allowed!
+  do_somthing
+else
+  raise "Too many requests. Resource available in #{SimpleThrottle[:things].wait_time} seconds"
+end
+```
+
+Calling `allow!` will return true if the throttle limit has not yet been reached and will also start tracking a new call if it returned true. There is no way to release a throttled call (that's why it's called SimpleThrottle).
+
+The throttle data is kept in redis as a list of timestamps and will be auto expired if it falls out of use. The thottles time windows are rolling time windows and more calls will be allowed as soon as possible.
+
+Redis server 2.6 or greater is required.

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler/gem_tasks"
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'RVM likes to call it tests'
+task :tests => :test
+
+begin
+  require 'rspec'
+  require 'rspec/core/rake_task'
+  desc 'Run the unit tests'
+  RSpec::Core::RakeTask.new(:test)
+rescue LoadError
+  task :test do
+    STDERR.puts "You must have rspec 2.0 installed to run the tests"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/simple_throttle.rb

@@ -0,0 +1,150 @@
+require 'redis'
+
+# Create a simple throttle that can be used to limit the number of request for a resouce
+# per time period. These objects are thread safe.
+class SimpleThrottle
+  
+  class << self
+    # Add a new throttle that can be referenced later with the [] method.
+    def add(name, limit:, ttl:)
+      @throttles ||= {} 
+      @throttles[name.to_s] = new(name, limit: limit, ttl: ttl)       
+    end
+    
+    # Returns a globally defined throttle with the specfied name.
+    def [](name)
+      if defined?(@throttles) && @throttles
+        @throttles[name.to_s]
+      else
+        nil
+      end
+    end
+    
+    # Set the Redis instance to use for maintaining the throttle. This can either be set
+    # with a hard coded value or by the value yielded by a block. If the block form is used
+    # it will be invoked at runtime to get the instance. Use this method if your Redis instance
+    # isn't constant (for example if you're in a forking environment and re-initialize connections
+    # on fork)
+    def set_redis(client = nil, &block)
+      @redis_client = (client || block)
+    end
+    
+    # Return the Redis instance where the throttles are stored.
+    def redis
+      if @redis_client.is_a?(Proc)
+        @redis_client.call
+      else
+        @redis_client
+      end
+    end
+  end
+  
+  attr_reader :name, :limit, :ttl
+  
+  # Create a new throttle with the given name. The ttl argument specifies the time
+  # range that is being used for measuring in seconds while the limit specifies how
+  # many calls are allowed in that range.
+  def initialize(name, limit:, ttl:)
+    @name = name.to_s
+    @name.freeze unless @name.frozen?
+    @limit = limit
+    @ttl = ttl
+    @script_sha_1 = nil
+  end
+  
+  # Returns true if the limit for the throttle has not been reached yet. This method
+  # will also track the throttled resource as having been invoked on each call.
+  def allowed!
+    size = current_size(true)
+    if size < limit
+      true
+    else
+      false
+    end
+  end
+  
+  # Reset a throttle back to zero.
+  def reset!
+    self.class.redis.del(redis_key)
+  end
+  
+  # Peek at the current number for throttled calls being tracked.
+  def peek
+    current_size(false)
+  end
+  
+  # Returns when the next resource call should be allowed. Note that this doesn't guarantee that
+  # calling allow! will return true if the wait time is zero since other processes or threads can
+  # claim the resource.
+  def wait_time
+    if peek < limit
+      0.0
+    else
+      first = self.class.redis.lindex(redis_key, 0).to_f / 1000.0
+      delta = Time.now.to_f - first
+      delta = 0.0 if delta < 0
+      delta
+    end
+  end
+    
+  private
+  
+  # Evaluate and execute a Lua script on the redis server that returns the number calls currently being tracked.
+  # If push is set to true then a new item will be added to the list.
+  def current_size(push)
+    redis = self.class.redis
+    @script_sha_1 ||= redis.script(:load, lua_script)
+    begin
+      push_arg = (push ? 1 : 0)
+      time_ms = (Time.now.to_f * 1000).round
+      ttl_ms = ttl * 1000
+      redis.evalsha(@script_sha_1, [], [redis_key, limit, ttl_ms, time_ms, push_arg])
+    rescue Redis::CommandError => e
+      if e.message.include?('NOSCRIPT'.freeze)
+        @script_sha_1 = redis.script(:load, lua_script)
+        retry
+      else
+        raise e
+      end
+    end
+  end
+  
+  def redis_key
+    "simple_throttle.#{name}"
+  end
+  
+  # Server side Lua script that maintains the throttle in redis. The throttle is stored as a list
+  # of timestamps in milliseconds. When the script is invoked it will scan the oldest entries
+  # removing any that should be expired from the list. If the list is below the specified limit
+  # 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.
+  def lua_script
+    <<-LUA
+    local list_key = ARGV[1]
+    local limit = tonumber(ARGV[2])
+    local ttl = tonumber(ARGV[3])
+    local now = ARGV[4]
+    local push = tonumber(ARGV[5])
+    
+    local size = redis.call('llen', list_key)
+    if size >= limit then
+      local expired = tonumber(now) - ttl
+      while size > 0 do
+        local t = redis.call('lpop', list_key)
+        if tonumber(t) > expired then
+          redis.call('lpush', list_key, t)
+          break
+        end
+        size = size - 1
+      end
+    end
+
+    if push > 0 and size < limit then
+      redis.call('rpush', list_key, now)
+      redis.call('pexpire', list_key, ttl)
+    end
+    
+    return size
+    LUA
+  end
+end

data/simple_throttle.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = "simple_throttle"
+  spec.version       = File.read(File.expand_path("../VERSION", __FILE__)).chomp
+  spec.authors       = ["We Heart It", "Brian Durand"]
+  spec.email         = ["dev@weheartit.com", "bbdurand@gmail.com"]
+  spec.summary       = "Simple redis backed throttling mechanism to limit access to a resource"
+  spec.description   = "Simple redis backed throttling mechanism to limit access to a resource."
+  spec.homepage      = "https://github.com/weheartit/sidekiq_fast_enq"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency('redis')
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/spec/simple_throttle_spec.rb

@@ -0,0 +1,55 @@
+require 'spec_helper'
+
+describe SimpleThrottle do
+  
+  it "should tell if a call is allowed" do
+    throttle = SimpleThrottle.new("test_simple_throttle", limit: 3, ttl: 1)
+    throttle.reset!
+    other_throttle = SimpleThrottle.new("test_simple_throttle_2", limit: 3, ttl: 1)
+    other_throttle.reset!
+    
+    expect(throttle.peek).to eq 0
+    expect(throttle.allowed!).to eq true
+    expect(throttle.peek).to eq 1
+    expect(throttle.allowed!).to eq true
+    expect(throttle.peek).to eq 2
+    expect(throttle.allowed!).to eq true
+    expect(throttle.peek).to eq 3
+    expect(throttle.allowed!).to eq false
+    expect(throttle.peek).to eq 3
+    expect(throttle.allowed!).to eq false
+    wait_time = throttle.wait_time
+    expect(wait_time).to be > 0.0
+    expect(wait_time).to be <= 1.0
+    
+    expect(other_throttle.allowed!).to eq true
+    expect(other_throttle.peek).to eq 1
+    expect(other_throttle.wait_time).to eq 0.0
+    
+    sleep(1.1)
+
+    expect(throttle.allowed!).to eq true
+    sleep(0.3)
+    expect(throttle.allowed!).to eq true
+    sleep(0.3)
+    expect(throttle.allowed!).to eq true
+    sleep(0.3)
+    expect(throttle.allowed!).to eq false
+    sleep(0.3)
+    expect(throttle.allowed!).to eq true
+  end
+  
+  it "should be able to add global throttles" do
+    SimpleThrottle.add(:test_1, limit: 4, ttl: 60)
+    SimpleThrottle.add(:test_2, limit: 10, ttl: 3600)
+    t1 = SimpleThrottle["test_1"]
+    expect(t1.name).to eq "test_1"
+    expect(t1.limit).to eq 4
+    expect(t1.ttl).to eq 60
+    t1 = SimpleThrottle[:test_2]
+    expect(t1.name).to eq "test_2"
+    expect(t1.limit).to eq 10
+    expect(t1.ttl).to eq 3600
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+require File.expand_path('../../lib/simple_throttle', __FILE__)
+
+SimpleThrottle.set_redis(Redis.new)
+
+RSpec.configure do |config|
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: simple_throttle
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- We Heart It
+- Brian Durand
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-05-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  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: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: Simple redis backed throttling mechanism to limit access to a resource.
+email:
+- dev@weheartit.com
+- bbdurand@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT_LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/simple_throttle.rb
+- simple_throttle.gemspec
+- spec/simple_throttle_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/weheartit/sidekiq_fast_enq
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Simple redis backed throttling mechanism to limit access to a resource
+test_files:
+- spec/simple_throttle_spec.rb
+- spec/spec_helper.rb