chokepoint 0.1.0

data/LICENSE

@@ -0,0 +1,16 @@
+The MIT License (MIT) Copyright (c) 2011 Viximo, Inc.
+
+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,81 @@
+Chokepoint: Rate Limiter
+========================
+
+This library provides throttling for arbitary blocks. Chokepoint is based on Arto Bendiken's 
+rack-throttle library.
+
+* Chokepoint <http://github.com/Viximo/chokepoint>
+* Rack::Throttle <http://github.com/bendiken/rack-throttle>
+
+Features
+--------
+
+* Throttles a block by enforcing a minimum time interval between
+  subsequent calls or by enforcing a maximum number of calls in a given
+  duration (Daily, Hourly, Minute)
+* Stores rate-limiting counters in any key/value store implementation that
+  responds to `#[]`/`#[]=` (like Ruby's hashes) or to `#get`/`#set` (like
+  memcached or Redis).
+* Compatible with the gdbm binding included in Ruby's standard library.
+* Compatible with the memcached, memcache-client, memcache and
+  redis gems.
+* Compatible with Heroku's memcached add-on.
+* Compatible with Ruby 1.8.7 & 1.9
+
+Examples
+--------
+
+### Enforcing a minimum 3-second interval between calls
+
+    Chokepoint::Interval('my block', :min => 3.0).throttle do
+      ...
+    end
+
+### Allowing a maximum of 60 requests per minute
+
+    Chokepoint::Minute('my block', :max => 60).throttle do
+      ...
+    end
+  
+### Storing the rate-limiting counters on a Memcached server
+
+    require 'memcached'
+    
+    Checkpoint::Interval.new('my block', :cache => Memcached.new, :key_prefix => :throttle) do
+      ...
+    end
+
+Throttling Strategies
+---------------------
+
+Chokepoint supports four built-in throttling strategies:
+
+* `Chokepoint::Interval`: Throttles the application by enforcing a
+  minimum interval (by default, 1 second) between calls.
+* `Chokepoint::Minute`: Throttles the application by defining a
+  maximum number of allowed calls per minute (by default, 60).
+* `Chokepoint::Hourly`: Throttles the application by defining a
+  maximum number of allowed calls per hour (by default, 3,600).
+* `Chokepoint::Daily`: Throttles the application by defining a
+  maximum number of allowed calls per day (by default, 86,400).
+
+You can fully customize the implementation details of any of these strategies
+by simply subclassing one of the aforementioned default implementations.
+And, of course, should your application-specific requirements be
+significantly more complex than what we've provided for, you can also define
+entirely new kinds of throttling strategies by subclassing the
+`Chokepoint::Limiter` base class directly.
+
+Authors
+-------
+
+* [Matt Griffin](mailto:matt@griffinonline.org)
+
+Based on [rack-throttle] (Public Domain) work by
+[Arto Bendiken](mailto:arto.bendiken@gmail.com) and [Brendon Murphy](mailto:disposable.20.xternal@spamourmet.com>)
+
+
+License
+-------
+
+Distribution is allowed under the MIT License.

data/lib/chokepoint.rb

@@ -0,0 +1,11 @@
+module Chokepoint
+  autoload :Limiter,    'chokepoint/limiter'
+  autoload :Daily,      'chokepoint/daily'
+  autoload :Hourly,     'chokepoint/hourly'
+  autoload :Minute,     'chokepoint/minute'
+  autoload :Interval,   'chokepoint/interval'
+  autoload :TimeWindow, 'chokepoint/time_window'
+  autoload :VERSION,    'chokepoint/version'
+  
+  class RateLimitExceeded < RuntimeError; end
+end

data/lib/chokepoint/daily.rb

@@ -0,0 +1,44 @@
+module Chokepoint
+  ##
+  # This rate limiter strategy throttles the block by defining a
+  # maximum number of allowed calls per day (by default, 86,400
+  # requests per 24 hours, which works out to an average of 1 request per
+  # second).
+  #
+  # Note that this strategy doesn't use a sliding time window, but rather
+  # tracks requests per calendar day. This means that the throttling counter
+  # is reset at midnight (according to the local timezone) every
+  # night.
+  #
+  # @example Allowing up to 86,400 requests per day
+  #   Chokepoint::Daily.new('activity').throttle do ... end
+  #
+  # @example Allowing up to 1,000 requests per day
+  #   Chokepoint::Daily.new('activity', :max => 1000).throttle do ... end
+  #
+  class Daily < TimeWindow
+    ##
+    # @param  [String]                 name
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [Integer] :max   (86400)
+    def initialize(name, options = {})
+      super
+    end
+
+    ##
+    def max_per_day
+      @max_per_hour ||= options[:max] || 86_400
+    end
+
+    alias_method :max_per_window, :max_per_day
+
+    protected
+
+    ##
+    # @param  [Object] context
+    # @return [String]
+    def cache_key(context)
+      [super, Time.now.strftime('%Y-%m-%d')].join(':')
+    end
+  end
+end

data/lib/chokepoint/hourly.rb

@@ -0,0 +1,44 @@
+module Chokepoint
+  ##
+  # This rate limiter strategy throttles the block by defining a
+  # maximum number of allowed calls per hour (by default, 3,600
+  # requests per 60 minutes, which works out to an average of 1 request per
+  # second).
+  #
+  # Note that this strategy doesn't use a sliding time window, but rather
+  # tracks calls per distinct hour. This means that the throttling
+  # counter is reset every hour on the hour (according to the local
+  # timezone).
+  #
+  # @example Allowing up to 3,600 requests per hour
+  #   Chokepoint::Hourly.new('activity').throttle do ... end
+  #
+  # @example Allowing up to 100 requests per hour
+  #   Chokepoint::Hourly.new('activity', :max => 100).throttle do ... end
+  #
+  class Hourly < TimeWindow
+    ##
+    # @param  [String]                 name
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [Integer] :max   (3600)
+    def initialize(name, options = {})
+      super
+    end
+
+    ##
+    def max_per_hour
+      @max_per_hour ||= options[:max] || 3_600
+    end
+
+    alias_method :max_per_window, :max_per_hour
+
+    protected
+
+    ##
+    # @param  [Object] context
+    # @return [String]
+    def cache_key(context)
+      [super, Time.now.strftime('%Y-%m-%dT%H')].join(':')
+    end
+  end
+end

data/lib/chokepoint/interval.rb

@@ -0,0 +1,52 @@
+module Chokepoint
+  ##
+  # This rate limiter strategy throttles the block by enforcing a
+  # minimum interval (by default, 1 second) between subsequent allowed calls.
+  #
+  # @example Allowing up to two requests per second
+  #   Chokepoint::Interval.new('activity', :min => 0.5)   #  500 ms interval
+  #
+  # @example Allowing a request every two seconds
+  #   Chokepoint::Interval.new('activity', :min => 2)   #  2000 ms interval
+  #
+  class Interval < Limiter
+    ##
+    # @param  [String]                 name
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [Float] :min     (1.0)
+    def initialize(name, options = {})
+      super
+    end
+
+    ##
+    # Returns `true` if sufficient time (equal to or more than
+    # {#minimum_interval}) has passed since the last call.
+    #
+    # @param  [Object] context
+    # @return [Boolean]
+    def allowed?(context)
+      time_now = Time.now.to_f
+      last_call_time = cache_get(key = cache_key(context)) rescue nil
+      allowed = !last_call_time || (dt = time_now - last_call_time.to_f) >= minimum_interval
+      begin
+        cache_set(key, time_now)
+        allowed
+      rescue => e
+        # If an error occurred while trying to update the timestamp stored
+        # in the cache, we will fall back to allowing the request through.
+        # This prevents the application blowing up merely due to a
+        # backend cache server (Memcached, Redis, etc.) being offline.
+        allowed = true
+      end
+    end
+    
+    ##
+    # Returns the required minimal interval (in terms of seconds) that must
+    # elapse between two subsequent calls.
+    #
+    # @return [Float]
+    def minimum_interval
+      @min ||= (@options[:min] || 1.0).to_f
+    end
+  end
+end

data/lib/chokepoint/limiter.rb

@@ -0,0 +1,155 @@
+module Chokepoint
+  ##
+  # This is the base class for rate limiter implementations.
+  #
+  # @example Defining a rate limiter subclass
+  #   class MyLimiter < Limiter
+  #     def allowed?(request)
+  #       # TODO: custom logic goes here
+  #     end
+  #   end
+  #
+  class Limiter
+    attr_reader :name
+    attr_reader :options
+
+    ##
+    # @param  [String] name 
+    # @param  [Hash{Symbol => Object}]      options
+    # @option options [String]  :cache      (Hash.new)
+    # @option options [String]  :key_prefix (nil)
+    # @option options [Integer] :code       (403)
+    # @option options [String]  :message    ("Rate Limit Exceeded")
+    def initialize(name, options = {})
+      @name, @options = name, options
+    end
+
+    def throttle(context = nil)
+      allowed?(context) ? yield : rate_limit_exceeded(context)
+    end
+
+    ##
+    # Returns `false` if the rate limit has been exceeded for the given
+    # `request`, or `true` otherwise.
+    #
+    # Override this method in subclasses that implement custom rate limiter
+    # strategies.
+    #
+    # @param  [Object] context
+    # @return [Boolean]
+    def allowed?(context = nil)
+      case
+        when whitelisted?(context) then true
+        when blacklisted?(context) then false
+        else true # override in subclasses
+      end
+    end
+
+    ##
+    # Returns `true` if the originator of the given `request` is whitelisted
+    # (not subject to further rate limits).
+    #
+    # The default implementation always returns `false`. Override this
+    # method in a subclass to implement custom whitelisting logic.
+    #
+    # @param  [Object] context
+    # @return [Boolean]
+    # @abstract
+    def whitelisted?(context)
+      false
+    end
+
+    ##
+    # Returns `true` if the originator of the given `request` is blacklisted
+    # (not honoring rate limits, and thus permanently forbidden access
+    # without the need to maintain further rate limit counters).
+    #
+    # The default implementation always returns `false`. Override this
+    # method in a subclass to implement custom blacklisting logic.
+    #
+    # @param  [Object] context
+    # @return [Boolean]
+    # @abstract
+    def blacklisted?(context)
+      false
+    end
+
+    protected
+
+    ##
+    # @return [Hash]
+    def cache
+      case cache = (options[:cache] ||= {})
+        when Proc then cache.call
+        else cache
+      end
+    end
+
+    ##
+    # @param  [String] key
+    def cache_has?(key)
+      case
+        when cache.respond_to?(:has_key?)
+          cache.has_key?(key)
+        when cache.respond_to?(:get)
+          cache.get(key) rescue false
+        else false
+      end
+    end
+
+    ##
+    # @param  [String] key
+    # @return [Object]
+    def cache_get(key, default = nil)
+      case
+        when cache.respond_to?(:[])
+          cache[key] || default
+        when cache.respond_to?(:get)
+          cache.get(key) || default
+      end
+    end
+
+    ##
+    # @param  [String] key
+    # @param  [Object] value
+    # @return [void]
+    def cache_set(key, value)
+      case
+        when cache.respond_to?(:[]=)
+          begin
+            cache[key] = value
+          rescue TypeError => e
+            # GDBM throws a "TypeError: can't convert Float into String"
+            # exception when trying to store a Float. On the other hand, we
+            # don't want to unnecessarily coerce the value to a String for
+            # any stores that do support other data types (e.g. in-memory
+            # hash objects). So, this is a compromise.
+            cache[key] = value.to_s
+          end
+        when cache.respond_to?(:set)
+          cache.set(key, value)
+      end
+    end
+
+    ##
+    # @param  [Object] context
+    # @return [String]
+    def cache_key(context)
+      case
+        when options.has_key?(:key_prefix)
+          [options[:key_prefix], name].join(':')
+        else name
+      end
+    end
+
+
+    ##
+    # Raise a RateLimitExceeded error
+    #
+    # @param  [Object] context
+    # @return [void]
+    def rate_limit_exceeded(context)
+      raise RateLimitExceeded, "Rate Limit Exceeded for #{name}"
+    end
+  end
+end

data/lib/chokepoint/minute.rb

@@ -0,0 +1,43 @@
+module Chokepoint
+  ##
+  # This rate limiter strategy throttles the block by defining a
+  # maximum number of allowed calls per minute (by default, 60
+  # requests per minute, which works out to an average of 1 request per
+  # second).
+  #
+  # Note that this strategy doesn't use a sliding time window, but rather
+  # tracks calls per distinct minute. This means that the throttling
+  # counter is reset every minute.
+  #
+  # @example Allowing up to 60 requests/minute
+  #   Chokepoint::Minute.new('activity').throttle do ... end
+  #
+  # @example Allowing up to 100 requests per minute
+  #   Chokepoint::Minute.new('activity', :max => 100).throttle do ... end
+  #
+  class Minute < TimeWindow
+    ##
+    # @param  [String]                 name
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [Integer] :max   (60)
+    def initialize(name, options = {})
+      super 
+    end
+
+    ##
+    def max_per_minute
+      @max_per_hour ||= options[:max] || 60
+    end
+
+    alias_method :max_per_window, :max_per_minute
+
+    protected
+
+    ##
+    # @param  [Object] context
+    # @return [String]
+    def cache_key(context)
+      [super, Time.now.strftime('%Y-%m-%dT%H:%M')].join(':')
+    end
+  end
+end

data/lib/chokepoint/time_window.rb

@@ -0,0 +1,21 @@
+module Chokepoint
+  ##
+  class TimeWindow < Limiter
+    ##
+    # Returns `true` if fewer than the maximum number of requests permitted
+    # for the current window of time have been made.
+    #
+    # @param  [Object] context
+    # @return [Boolean]
+    def allowed?(context)
+      count = cache_get(key = cache_key(context)).to_i + 1 rescue 1
+      allowed = count <= max_per_window.to_i
+      begin
+        cache_set(key, count)
+        allowed
+      rescue => e
+        allowed = true
+      end
+    end
+  end
+end

data/lib/chokepoint/version.rb

@@ -0,0 +1,13 @@
+module Chokepoint
+
+  module VERSION
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+    
+    def self.to_s
+      [MAJOR, MINOR, PATCH].join('.')
+    end
+  end
+  
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification 
+name: chokepoint
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Matt Griffin
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-11-02 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 0
+        version: "2.0"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: timecop
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: Wrap arbitrary blocks with a chokpoint to throttle access. Chokepoints can be extended with various throttling behaviors as needed.
+email: matt@griffinonline.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/chokepoint.rb
+- lib/chokepoint/daily.rb
+- lib/chokepoint/hourly.rb
+- lib/chokepoint/interval.rb
+- lib/chokepoint/limiter.rb
+- lib/chokepoint/minute.rb
+- lib/chokepoint/time_window.rb
+- lib/chokepoint/version.rb
+- README.md
+- LICENSE
+has_rdoc: true
+homepage: https://github.com/Viximo/chokepoint
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.3
+signing_key: 
+specification_version: 3
+summary: Create chokepoints that throttle access to resources
+test_files: []
+