pause 0.0.4 → 0.0.5

data/.gitignore

@@ -16,3 +16,4 @@ test/tmp
 test/version_tmp
 tmp
 .idea
+.DS_Store

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012 TODO: Write your name
+Copyright (c) 2012 Wanelo, Inc
 
 MIT License
 
@@ -19,4 +19,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -3,9 +3,15 @@ Pause
 
 [![Build status](https://secure.travis-ci.org/wanelo/pause.png)](http://travis-ci.org/wanelo/pause)
 
-Pause is a Redis-backed rate-limiting client. Use it to track events, with
+Pause is a flexible Redis-backed rate-limiting client. Use it to track events, with
 rules around how often they are allowed to occur within configured time checks.
 
+Because Pause is Redis-based, multiple ruby processes (even distributed across multiple servers) can track and report
+events together, and then query whether a particular identifier should be rate limited or not.
+
+Sample applications include IP-based blocking based on HTTP request volume (see related gem "spanx"),
+throttling push notifications as to not overwhelm the user with too much frequency, etc.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -36,16 +42,15 @@ Pause.configure do |config|
   config.redis_host = "127.0.0.1"
   config.redis_port = 6379
   config.redis_db   = 1
-
-  config.resolution = 600
-  config.history    = 86400
+  config.resolution = 600     # aggregate all events into 10 minute blocks
+  config.history    = 86400   # discard all events older than 1 day
 end
 ```
 
 ### Actions
 
 Define local actions for your application. Actions define a scope by
-which they are identified in the persistent store, and a set of checks.  Checks define various
+which they are identified in the persistent store (aka "namespace"), and a set of checks.  Checks define various
 thresholds (`max_allowed`) against periods of time (`period_seconds`). When a threshold it triggered,
 the action is rate limited, and stays rate limited for the duration of `block_ttl` seconds.
 
@@ -62,9 +67,16 @@ Checks are configured with the following arguments (which can be passed as an ar
 Scope is simple string used to identify this action in the Redis store, and is appended to all keys.
 Therefore it is advised to keep scope as short as possible to reduce memory requirements of the store.
 
+If you are using the same Redis store to rate limit multiple actions, you must ensure that each action
+has a unique scope.
+
 #### Resolution
 
-Note that your resolution must be less than or equal to the smallest `period_seconds` value in your checks.
+Resolution is the period of aggregation.  As events come in, Pause aggregates them in time blocks
+of this length.  If you set resolution to 10 minutes, all events arriving within a 10 minute block
+are aggregated.
+
+Resolution must be less than or equal to the smallest `period_seconds` value in your checks.
 In other words, if your shortest check is 1 minute, you could set resolution to 1 minute or smaller.
 
 #### Example
@@ -88,6 +100,7 @@ class FollowsController < ApplicationController
     action = FollowAction.new(user.id)
     if action.ok?
       # do stuff!
+      # and track it...
       action.increment!
     else
       # action is rate limited, either skip
@@ -99,7 +112,10 @@ end
 class OtherController < ApplicationController
   def index
     action = OtherAction.new(params[:thing])
-    if action.ok?
+    unless action.rate_limited?
+      # perform business logic
+      ....
+      # track it
       action.increment!(params[:count].to_i, Time.now.to_i)
     end
   end
@@ -109,25 +125,55 @@ end
 If more data is needed about why the action is blocked, the `analyze` can be called
 
 ```ruby
-action = MyAction.new("thing")
+action = NotifyViaEmailAction.new("thing")
 
 while true
   action.increment!
 
-  blocked_action = action.analyze
-
-  if blocked_action
-    puts blocked_action.identifier
-    puts blocked_action.sum
-    puts blocked_action.timestamp
-
-    puts blocked_aciton.period_check.inspect
+  rate_limit_event = action.analyze
+  if rate_limit_event
+    puts rate_limit_event.identifier               # which key got rate limited ("thing")
+    puts rate_limit_event.sum                      # total count that triggered a rate limit
+    puts rate_limit_event.timestamp                # timestamp when rate limiting occurred
+    puts rate_limit_event.period_check             # period check object, that triggered this rate limiting event
+  else
+    # not rate-limited, same as action.ok?
   end
 
   sleep 1
 end
 ```
 
+## Enabling/Disabling Actions
+
+Actions have a built-in way by which they can be disabled or enabled.
+
+```ruby
+MyAction.disable
+MyAction.enable
+```
+
+This is persisted to Redis, so state is not process-bound, but shared across all ruby run-times using this
+action (assuming Redis store configuration is the same).
+
+When disabled, Pause does *not* check state in any of its methods, so calls to increment! or ok? still work
+exactly as before. This is because adding extra Redis calls can be expensive in loops. You should check
+whether your action is enabled or disabled if it important to support enabling and disabling of rate limiting in
+your context.
+
+```ruby
+while true
+  if MyAction.enabled?
+    Thing.all.each do |thing|
+      action = MyAction.new(thing.name)
+      action.increment! unless action.rate_limited?
+    end
+  end
+  sleep 10
+end
+```
+
+
 ## Contributing
 
 Want to make it better? Cool. Here's how:
@@ -137,3 +183,11 @@ Want to make it better? Cool. Here's how:
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new pull request
+
+## Authors
+
+This gem was written by Eric Saxby, Atasay Gokkaya and Konstantin Gredeskoul at Wanelo, Inc.
+
+Please see the LICENSE.txt file for further details.
+
+

data/lib/pause/action.rb

@@ -67,6 +67,9 @@ module Pause
 
     def ok?
       Pause.analyzer.check(self).nil?
+    rescue ::Redis::CannotConnectError => e
+      $stderr.puts "Error connecting to redis: #{e.inspect}"
+      false
     end
 
     def analyze

data/lib/pause/redis/adapter.rb

@@ -2,6 +2,8 @@ require 'pause/helper/timing'
 
 module Pause
   module Redis
+
+    # This class encapsulates Redis operations used by Pause
     class Adapter
 
       include Pause::Helper::Timing

data/lib/pause/version.rb

@@ -1,3 +1,3 @@
 module Pause
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/pause.gemspec

@@ -6,10 +6,10 @@ require 'pause/version'
 Gem::Specification.new do |gem|
   gem.name          = "pause"
   gem.version       = Pause::VERSION
-  gem.authors       = ["Atasay Gokkaya", "Paul Henry", "Eric Saxby"]
-  gem.email         = %w(atasay@wanelo.com paul@wanelo.com sax@wanelo.com)
-  gem.description   = %q(Real time redis rate limiting)
-  gem.summary       = %q(Real time redis rate limiting)
+  gem.authors       = ["Atasay Gokkaya", "Paul Henry", "Eric Saxby", "Konstantin Gredeskoul"]
+  gem.email         = %w(atasay@wanelo.com paul@wanelo.com sax@wanelo.com kig@wanelo.com)
+  gem.description   = %q(Real time rate limiting for multi-process ruby environments based on Redis)
+  gem.summary       = %q(RReal time rate limiting for multi-process ruby environments based on Redis)
   gem.homepage      = "https://github.com/wanelo/pause"
 
   gem.files         = `git ls-files`.split($/)

data/spec/pause/action_spec.rb

@@ -60,6 +60,15 @@ describe Pause::Action do
       action.ok?.should be_false
 
     end
+
+    it "should return false and silently fail if redis is not available" do
+      Redis.any_instance.stub(:zrange) { raise Redis::CannotConnectError }
+      time = period_marker(resolution, Time.now.to_i)
+
+      action.increment! 4, time - 25
+
+      action.ok?.should be_false
+    end
   end
 
   describe "#analyze" do

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: pause
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
 - Atasay Gokkaya
 - Paul Henry
 - Eric Saxby
+- Konstantin Gredeskoul
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-14 00:00:00.000000000 Z
+date: 2012-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -109,11 +110,13 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Real time redis rate limiting
+description: Real time rate limiting for multi-process ruby environments based on
+  Redis
 email:
 - atasay@wanelo.com
 - paul@wanelo.com
 - sax@wanelo.com
+- kig@wanelo.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -166,7 +169,7 @@ rubyforge_project:
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: Real time redis rate limiting
+summary: RReal time rate limiting for multi-process ruby environments based on Redis
 test_files:
 - spec/pause/action_spec.rb
 - spec/pause/analyzer_spec.rb