restrainer 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c864dec39322b1a42a062119de6bac2a5a9134db
+  data.tar.gz: 2cbc9b6c3b78a4b6bb4fd706bdc645543366a6a6
+SHA512:
+  metadata.gz: 275f22b4379067198e130603461ccd92b0da8e85ef05dd9fe142fa02c6e202b358b9512cbd8146b7c5ded56145380e2ab9b168f729ed8c00223300321217ab18
+  data.tar.gz: 9c30e5358e500d7172a4dd3924e5c64018fb4daed80d8a781786846ae9b7f0069e167af5156fc38b389c991e8a2c7ce08d1262155ed89c43dd6ae39d2fefcd13

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/MIT_LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 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,40 @@
+This gem provides a method of throttling calls across processes that can be very useful if you have to call an external service with limited resources.
+
+A [redis server](http://redis.io/) is required to use this gem.
+
+### Usage
+
+This code will throttle all calls to the mythical MyService so that no more than 100 calls are ever being made at a single time across all application processes.
+
+```ruby
+restrainer = Restrainer.new(:my_service, limit: 100)
+restrainer.throttle do
+  MyServiceClient.call
+end
+```
+
+You can also override the limit in the `throttle` method. Setting a limit of zero will disable processing entirely. Setting a limit less than zero will remove the limit. Note that the limit set in the throttle is not shared with other processes, but the count of the number of processes is shared. Thus it is possible to have the throttle allow one process but reject another if the limits are different.
+
+Instances of Restrainer do not use any internal state to keep track of number of running processes. All of that information is maintained in redis. Therefore you don't need to worry about maintaining references to Restrainer instances and you can create them as needed as long as they are named consistently. You can create multiple Restrainers for different uses in your application by simply giving them different names.
+
+### Configuration
+
+To set the redis connection used by for the gem you can either specify a block that yields a Redis object (from the [redis](https://github.com/redis/redis-rb) gem) or you can explicitly set the attribute. The block form is generally preferred since it can work with connection pools, etc.
+
+```ruby
+Restrainer.redis{ connection_pool.redis }
+
+Restrainer.redis = redis_client
+```
+
+### Internals
+
+To protect against situations where a process is killed without a chance to cleanup after itself (i.e. `kill -9`), each process is only tracked for a limited amount of time (one minute by default). After this time, the Restrainer will assume that the process has been orphaned and removes it from the list.
+
+The timeout can be set by the timeout option on the constructor. If you have any timeouts set on the services being called in the block, you should set the Restrainer timeout to a slightly higher value.
+
+```ruby
+restrainer = Restrainer.new(:my_service, 100, timeout: 10)
+```
+
+This gem does clean up after itself nicely, so that it won't ever leave unused data lying around in redis.

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/restrainer.rb

@@ -0,0 +1,130 @@
+require 'redis'
+require 'securerandom'
+
+# Redis backed throttling mechanism to ensure that only a limited number of processes can
+# be executed at any one time.
+#
+# Usage:
+#   Restrainer.new(:foo, 10).throttle do
+#     # Do something
+#   end
+#
+# If more than the specified number of processes as identified by the name argument is currently
+# running, then the throttle block will raise an error.
+class Restrainer
+  
+  attr_reader :name, :limit
+  
+  class ThrottledError < StandardError
+  end
+  
+  class << self
+    # Either configure the redis instance using a block or yield the instance. Configuring with
+    # a block allows you to use things like connection pools etc. without hard coding a single
+    # instance.
+    #
+    # Example: `Restrainer.redis{ redis_pool.instance }
+    def redis(&block)
+      if block
+        @redis = block
+      elsif defined?(@redis) && @redis
+        @redis.call
+      else
+        raise "#{self.class.name}.redis not configured"
+      end
+    end
+    
+    # Set the redis instance to a specific instance. It is usually preferable to use the block
+    # form for configurating the instance.
+    def redis=(conn)
+      @redis = lambda{ conn }
+    end
+  end
+  
+  # Create a new restrainer. The name is used to identify the Restrainer and group processes together.
+  # You can create any number of Restrainers with different names.
+  #
+  # The required limit parameter specifies the maximum number of processes that will be allowed to execute the
+  # throttle block at any point in time.
+  #
+  # The timeout parameter is used for cleaning up internal data structures so that jobs aren't orphaned 
+  # if their process is killed. Processes will automatically be removed from the running jobs list after the
+  # specified number of seconds. Note that the Restrainer will not handle timing out any code itself. This
+  # value is just used to insure the integrity of internal data structures.
+  def initialize(name, limit:, timeout: 60)
+    @name = name
+    @limit = limit
+    @timeout = timeout
+    @key = "#{self.class.name}.#{name.to_s}"
+  end
+  
+  # Wrap a block with this method to throttle concurrent execution. If more than the alotted number
+  # of processes (as identified by the name) are currently executing, then a Restrainer::ThrottledError
+  # will be raised.
+  #
+  # The limit argument can be used to override the value set in the constructor.
+  def throttle(limit: nil)
+    limit ||= self.limit
+    
+    # limit of less zero is no limit; limit of zero is allow none
+    return yield if limit < 0
+    raise ThrottledError.new("#{self.class}: #{@name} is not allowing any processing") if limit == 0
+    
+    # Grab a reference to the redis instance to that it will be consistent throughout the method
+    redis = self.class.redis
+    check_running_count!(redis, limit)
+    process_id = SecureRandom.uuid
+    begin
+      add_process!(redis, process_id)
+      yield
+    ensure
+      remove_process!(redis, process_id)
+    end
+  end
+  
+  # Get the number of processes currently being executed for this restrainer.
+  def current(redis = nil)
+    redis ||= self.class.redis
+    redis.zcard(key).to_i
+  end
+  
+  private
+  
+  # Hash key in redis to story a sorted set of current processes.
+  def key
+    @key
+  end
+  
+  # Raise an error if there are too many running processes.
+  def check_running_count!(redis, limit)
+    running_count = current(redis)
+    if running_count >= limit
+      running_count = current(redis) if cleanup!(redis)
+      if running_count >= limit
+        raise ThrottledError.new("#{self.class}: #{@name} already has #{running_count} processes running")
+      end
+    end
+  end
+  
+  # Add a process to the currently run set.
+  def add_process!(redis, process_id)
+    redis.multi do |conn|
+      conn.zadd(key, Time.now.to_i, process_id)
+      conn.expire(key, @timeout)
+    end
+  end
+  
+  # Remove a process to the currently run set.
+  def remove_process!(redis, process_id)
+    redis.zrem(key, process_id)
+  end
+  
+  # Protect against kill -9 which can cause processes to not be removed from the lists.
+  # Processes will be assumed to have finished by a specified timeout (in seconds).
+  def cleanup!(redis)
+    max_score = Time.now.to_i - @timeout
+    expired = redis.zremrangebyscore(key, "-inf", max_score)
+    expired > 0 ? true : false
+  end
+  
+end

data/restrainer.gemspec

@@ -0,0 +1,27 @@
+# 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          = "restrainer"
+  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       = "Code for throttling workloads so as not to overwhelm external services"
+  spec.description   = "Code for throttling workloads so as not to overwhelm external services."
+  spec.homepage      = "https://github.com/weheartit/restrainer"
+  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.required_ruby_version = '>=2.0'
+
+  spec.add_dependency('redis')
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "timecop"
+end

data/spec/restrainer_spec.rb

@@ -0,0 +1,70 @@
+require 'spec_helper'
+
+describe Restrainer do
+  
+  it "should have a name and max_processes" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 1)
+    expect(restrainer.name).to eq(:restrainer_test)
+    expect(restrainer.limit).to eq(1)
+  end
+  
+  it "should run a block" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 1)
+    x = nil
+    expect(restrainer.throttle{ x = restrainer.current }).to eq(1)
+    expect(x).to eq(1)
+    expect(restrainer.current).to eq(0)
+  end
+  
+  it "should throw an error if too many processes are already running" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 1)
+    x = nil
+    restrainer.throttle do
+      expect(lambda{restrainer.throttle{ x = 1 }}).to raise_error(Restrainer::ThrottledError)
+    end
+    expect(x).to eq(nil)
+  end
+  
+  it "should not throw an error if the number of processes is under the limit" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 2)
+    x = nil
+    restrainer.throttle do
+      restrainer.throttle{ x = 1 }
+    end
+    expect(x).to eq(1)
+  end
+  
+  it "should let the throttle method override the limit" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 1)
+    x = nil
+    restrainer.throttle do
+      restrainer.throttle(limit: 2){ x = 1 }
+    end
+    expect(x).to eq(1)
+  end
+  
+  it "should allow processing to be turned off entirely by setting the limit to zero" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 1)
+    x = nil
+    expect(lambda{restrainer.throttle(limit: 0){ x = 1 }}).to raise_error(Restrainer::ThrottledError)
+    expect(x).to eq(nil)
+  end
+  
+  it "should allow the throttle to be opened up entirely with a negative limit" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 0)
+    x = nil
+    restrainer.throttle(limit: -1){ x = 1 }
+    expect(x).to eq(1)
+  end
+  
+  it "should cleanup the running process list if orphaned processes exist" do
+    restrainer = Restrainer.new(:restrainer_test, limit: 1, timeout: 10)
+    x = nil
+    restrainer.throttle do
+      Timecop.travel(11) do
+        restrainer.throttle{ x = 1 }
+      end
+    end
+    expect(x).to eq(1)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+require File.expand_path('../../lib/restrainer', __FILE__)
+require 'timecop'
+
+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'
+  
+  Restrainer.redis = Redis.new
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: restrainer
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- We Heart It
+- Brian Durand
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-30 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'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  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: Code for throttling workloads so as not to overwhelm external services.
+email:
+- dev@weheartit.com
+- bbdurand@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- MIT_LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/restrainer.rb
+- restrainer.gemspec
+- spec/restrainer_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/weheartit/restrainer
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.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: Code for throttling workloads so as not to overwhelm external services
+test_files:
+- spec/restrainer_spec.rb
+- spec/spec_helper.rb