pause 0.0.3 → 0.0.4

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - 1.9.3
+script: "bundle exec rspec"
+notifications:
+  email:
+    recipients:
+      - dev@wanelo.com
+    on_success: never
+    on_failure: always

data/README.md

@@ -1,6 +1,8 @@
 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
 rules around how often they are allowed to occur within configured time checks.
 
@@ -20,6 +22,8 @@ Or install it yourself as:
 
 ## Usage
 
+### Configuration
+
 Configure Pause. This could be in a Rails initializer.
 
   * resolution - The time resolution (in seconds) defining the minimum period into which action counts are
@@ -38,26 +42,40 @@ Pause.configure do |config|
 end
 ```
 
-Define local actions for your application. These should define a scope, by
-which they are identified in the persistent store, and checks.
+### 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
+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.
+
+#### Checks
+
+Checks are configured with the following arguments (which can be passed as an array, or a symbol hash):
+
+  * `period_seconds` - time window this is a time period against which an action is tested
+  * `max_allowed` - the maximum number of times an action can be incremented during this particular time period before rate limiting is triggered.
+  * `block_ttl` - amount time (seconds) an action stays rate limited after threshold is reached.
+
+#### Scope
+
+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.
 
-Checks are configured with the following arguments:
+#### Resolution
 
-  * `period_seconds` - this is a period of time against which an action is tested
-  * `max_allowed` - the maximum number of times an action can be incremented during the time block determined by
-                  period seconds
-  * `block_ttl` - how long to mark an action as blocked if it goes over max-allowed
+Note that your 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.
 
-Note that you should not configure a check with `period_seconds` less than the minimum resolution set in the
-Pause config. If you do so, you will actually be checking sums against the full time period.
+#### Example
 
 ```ruby
 require 'pause'
 
 class FollowAction < Pause::Action
-  scope "ipn:follow"
-  check 600, 100, 300
-  check 3600, 200, 1200
+  scope "f"
+  check period_seconds:   60, max_allowed:  100, block_ttl: 3600
+  check period_seconds: 1800, max_allowed: 2000, block_ttl: 3600
 end
 ```
 
@@ -69,10 +87,11 @@ class FollowsController < ApplicationController
   def create
     action = FollowAction.new(user.id)
     if action.ok?
-      # do stuff
+      # do stuff!
       action.increment!
     else
-      # show errors
+      # action is rate limited, either skip
+      # or show error, depending on the context.
     end
   end
 end
@@ -81,7 +100,7 @@ class OtherController < ApplicationController
   def index
     action = OtherAction.new(params[:thing])
     if action.ok?
-      action.increment!(Time.now.to_i, params[:count].to_i)
+      action.increment!(params[:count].to_i, Time.now.to_i)
     end
   end
 end

data/lib/pause.rb

@@ -1,9 +1,10 @@
+require 'redis'
 require "pause/version"
 require "pause/configuration"
 require "pause/action"
 require "pause/analyzer"
 require "pause/redis/adapter"
-require 'pause/blocked_action'
+require 'pause/rate_limited_event'
 
 module Pause
   class PeriodCheck < Struct.new(:period_seconds, :max_allowed, :block_ttl)

data/lib/pause/action.rb

@@ -25,17 +25,23 @@ module Pause
     # Action subclasses should define their checks as follows
     #
     #  period_seconds - compare all activity by an identifier within the time period
-    #  max_allowed - if the number of actions by an identifier exceeds max_allowed for the time period marked
-    #                by period_seconds, it is no longer ok.
-    #  ttl - time to mark identifier as not ok
+    #  max_allowed    - if the number of actions by an identifier exceeds max_allowed for the time period marked
+    #                   by period_seconds, it is no longer ok.
+    #  block_ttl      - time to mark identifier as not ok
     #
     #     class MyAction < Pause::Action
-    #       check 10, 20, 30 # period_seconds, max_allowed, ttl
-    #       check 20, 30, 40 # period_seconds, max_allowed, ttl
+    #       check period_seconds: 60,   max_allowed: 100,  block_ttl: 3600
+    #       check period_seconds: 1800, max_allowed: 2000, block_ttl: 3600
     #     end
     #
-    def self.check(period_seconds, max_allowed, block_ttl)
+    def self.check(*args)
       @checks ||= []
+      period_seconds, max_allowed, block_ttl =
+        if args.first.is_a?(Hash)
+          [args.first[:period_seconds], args.first[:max_allowed], args.first[:block_ttl]]
+        else
+          args
+        end
       @checks << Pause::PeriodCheck.new(period_seconds, max_allowed, block_ttl)
     end
 
@@ -51,17 +57,19 @@ module Pause
       @checks = period_checks
     end
 
-    def increment!(timestamp = Time.now.to_i, count = 1)
+    def increment!(count = 1, timestamp = Time.now.to_i)
       Pause.analyzer.increment(self, timestamp, count)
     end
 
+    def rate_limited?
+      ! ok?
+    end
+
     def ok?
-      return true if self.class.disabled?
       Pause.analyzer.check(self).nil?
     end
 
     def analyze
-      return nil if self.class.disabled?
       Pause.analyzer.check(self)
     end
 
@@ -69,12 +77,12 @@ module Pause
       Pause.analyzer.tracked_identifiers(self.class_scope)
     end
 
-    def self.blocked_identifiers
-      Pause.analyzer.blocked_identifiers(self.class_scope)
+    def self.rate_limited_identifiers
+      Pause.analyzer.rate_limited_identifiers(self.class_scope)
     end
 
     def self.unblock_all
-      Pause.analyzer.adapter.delete_keys(self.class_scope)
+      Pause.analyzer.adapter.delete_rate_limited_keys(self.class_scope)
     end
 
     def key

data/lib/pause/analyzer.rb

@@ -22,8 +22,8 @@ module Pause
       adapter.all_keys(scope)
     end
 
-    def blocked_identifiers(scope)
-      adapter.blocked_keys(scope)
+    def rate_limited_identifiers(scope)
+      adapter.rate_limited_keys(scope)
     end
 
     private
@@ -37,10 +37,10 @@ module Pause
           break if element.ts < start_time
           sum += element.count
           if sum >= period_check.max_allowed
-            adapter.block(action.key, period_check.block_ttl)
+            adapter.rate_limit!(action.key, period_check.block_ttl)
             # Note that Time.now is different from period_marker(resolution, Time.now), which
             # rounds down to the nearest (resolution) seconds
-            return Pause::BlockedAction.new(action, period_check, sum, Time.now.to_i)
+            return Pause::RateLimitedEvent.new(action, period_check, sum, Time.now.to_i)
           end
           sum
         end

data/lib/pause/{blocked_action.rb → rate_limited_event.rb}

@@ -1,5 +1,5 @@
 module Pause
-  class BlockedAction
+  class RateLimitedEvent
     attr_accessor :action, :identifier, :period_check, :sum, :timestamp
 
     def initialize(action, period_check, sum, timestamp)

data/lib/pause/redis/adapter.rb

@@ -31,27 +31,27 @@ module Pause
         extract_set_elements(white_key(key))
       end
 
-      def block(key, block_ttl)
-        redis.setex(blocked_key(key), block_ttl, nil)
+      def rate_limit!(key, block_ttl)
+        redis.setex(rate_limited_key(key), block_ttl, nil)
       end
 
-      def blocked?(key)
-        !!redis.get(blocked_key(key))
+      def rate_limited?(key)
+        !!redis.get(rate_limited_key(key))
       end
 
       def all_keys(scope)
         keys(white_key(scope))
       end
 
-      def blocked_keys(scope)
-        keys(blocked_key(scope))
+      def rate_limited_keys(scope)
+        keys(rate_limited_key(scope))
       end
 
-      def delete_keys(scope)
-        ids = blocked_keys(scope)
+      def delete_rate_limited_keys(scope)
+        ids = rate_limited_keys(scope)
         increment_keys = ids.map{ |key| white_key(scope, key) }
-        blocked_keys = ids.map{ |key| blocked_key(scope, key) }
-        redis.del (increment_keys + blocked_keys)
+        rate_limited_keys = ids.map{ |key| rate_limited_key(scope, key) }
+        redis.del (increment_keys + rate_limited_keys)
       end
 
       def disable(scope)
@@ -82,7 +82,7 @@ module Pause
         ["i", scope, key].compact.join(':')
       end
 
-      def blocked_key(scope, key = nil)
+      def rate_limited_key(scope, key = nil)
         ["b", scope, key].compact.join(':')
       end
 

data/lib/pause/version.rb

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

data/pause.gemspec

@@ -6,7 +6,7 @@ require 'pause/version'
 Gem::Specification.new do |gem|
   gem.name          = "pause"
   gem.version       = Pause::VERSION
-  gem.authors       = ["Atasay Gokkaya", "Paul Henry", "Eric Saxny"]
+  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)

data/spec/pause/action_spec.rb

@@ -6,8 +6,8 @@ describe Pause::Action do
 
   class MyNotification < Pause::Action
     scope "ipn:follow"
-    check 20, 5, 40
-    check 40, 7, 40
+    check period_seconds: 20, max_allowed: 5, block_ttl: 40
+    check period_seconds: 40, max_allowed: 7, block_ttl: 40
   end
 
   let(:resolution) { 10 }
@@ -47,73 +47,45 @@ describe Pause::Action do
     end
 
     it "should successfully consider different period checks" do
-      time = period_marker(resolution, Time.now.to_i + 1)
+      time = period_marker(resolution, Time.now.to_i)
 
-      Timecop.freeze Time.at(time - 35) do
-        4.times do
-          action.increment!
-          action.ok?.should be_true
-        end
-      end
-
-      Timecop.freeze Time.at(time - 5) do
-        2.times do
-          action.increment!
-          action.ok?.should be_true
-        end
-        action.increment!
-        action.ok?.should be_false
-      end
-    end
+      action.increment! 4, time - 25
+      action.ok?.should be_true
 
-    context "action is disabled" do
+      action.increment! 2, time - 3
+      action.ok?.should be_true
 
-      it "should be true if action is disabled, even if blocked" do
-        10.times { action.increment! }
-        action.ok?.should be_false
+      action.increment! 1, time
 
-        MyNotification.disable
+      action.ok?.should be_false
 
-        action.ok?.should be_true
-      end
     end
   end
 
   describe "#analyze" do
-    context "action should not be blocked" do
+    context "action should not be rate limited" do
       it "returns nil" do
         action.analyze.should be_nil
       end
     end
 
-    context "action should be blocked" do
-      it "returns a BlockedAction object" do
+    context "action should be rate limited" do
+      it "returns a RateLimitedEvent object" do
         time = Time.now
-        blocked_action = nil
+        rate_limit = nil
 
         Timecop.freeze time do
           7.times { action.increment! }
-          blocked_action = action.analyze
+          rate_limit = action.analyze
         end
 
-        expected_blocked_action = Pause::BlockedAction.new(action, action.checks[0], 7, time.to_i)
-
-        blocked_action.should be_a(Pause::BlockedAction)
-        blocked_action.identifier.should == expected_blocked_action.identifier
-        blocked_action.sum.should == expected_blocked_action.sum
-        blocked_action.period_check.should == expected_blocked_action.period_check
-        blocked_action.timestamp.should == expected_blocked_action.timestamp
-      end
-    end
+        expected_rate_limit = Pause::RateLimitedEvent.new(action, action.checks[0], 7, time.to_i)
 
-    context "action is disabled" do
-      it "return nil, even if blocked" do
-        10.times { action.increment! }
-        action.should_not be_ok
-
-        MyNotification.disable
-
-        action.analyze.should be_nil
+        rate_limit.should be_a(Pause::RateLimitedEvent)
+        rate_limit.identifier.should == expected_rate_limit.identifier
+        rate_limit.sum.should == expected_rate_limit.sum
+        rate_limit.period_check.should == expected_rate_limit.period_check
+        rate_limit.timestamp.should == expected_rate_limit.timestamp
       end
     end
   end
@@ -131,16 +103,16 @@ describe Pause::Action do
     end
   end
 
-  describe "#blocked_identifiers" do
+  describe "#rate_limited_identifiers" do
     it "should return all the identifiers blocked" do
-      action.increment!(Time.now.to_i, 100)
-      other_action.increment!(Time.now.to_i, 100)
+      action.increment!(100, Time.now.to_i)
+      other_action.increment!(100, Time.now.to_i)
 
       action.ok?
       other_action.ok?
 
-      MyNotification.blocked_identifiers.should include(action.identifier)
-      MyNotification.blocked_identifiers.should include(other_action.identifier)
+      MyNotification.rate_limited_identifiers.should include(action.identifier)
+      MyNotification.rate_limited_identifiers.should include(other_action.identifier)
     end
   end
 
@@ -153,11 +125,11 @@ describe Pause::Action do
       other_action.ok?
 
       MyNotification.tracked_identifiers.should include(action.identifier, other_action.identifier)
-      MyNotification.blocked_identifiers.should == [action.identifier]
+      MyNotification.rate_limited_identifiers.should == [action.identifier]
 
       MyNotification.unblock_all
 
-      MyNotification.blocked_identifiers.should be_empty
+      MyNotification.rate_limited_identifiers.should be_empty
       MyNotification.tracked_identifiers.should == [other_action.identifier]
     end
   end
@@ -174,9 +146,13 @@ describe Pause::Action, ".check" do
     check 300, 150, 200
   end
 
+  class ActionWithHashChecks < Pause::Action
+    check period_seconds: 50, block_ttl: 60, max_allowed: 100
+  end
+
   it "should define a period check on new instances" do
     ActionWithCheck.new("id").checks.should == [
-        Pause::PeriodCheck.new(100, 150, 200),
+        Pause::PeriodCheck.new(100, 150, 200)
     ]
   end
 
@@ -188,6 +164,12 @@ describe Pause::Action, ".check" do
     ]
   end
 
+  it "should accept hash arguments" do
+    ActionWithHashChecks.new("id").checks.should == [
+        Pause::PeriodCheck.new(50, 100, 60)
+    ]
+  end
+
 end
 
 describe Pause::Action, ".scope" do

data/spec/pause/analyzer_spec.rb

@@ -37,7 +37,7 @@ describe Pause::Analyzer do
   describe "#analyze" do
     it "checks and blocks if max_allowed is reached" do
       time = Time.now
-      adapter.should_receive(:block).once.with(action.key, 12)
+      adapter.should_receive(:rate_limit!).once.with(action.key, 12)
       Timecop.freeze time do
         5.times do
           analyzer.increment(action)
@@ -57,7 +57,7 @@ describe Pause::Analyzer do
         5.times do
           analyzer.increment(action)
         end
-        analyzer.check(action).should be_a(Pause::BlockedAction)
+        analyzer.check(action).should be_a(Pause::RateLimitedEvent)
       end
     end
   end

data/spec/pause/redis/adapter_spec.rb

@@ -53,7 +53,7 @@ describe Pause::Redis::Adapter do
     let(:ttl) { 110000 }
 
     it "saves ip to redis with expiration" do
-      adapter.block(key, ttl)
+      adapter.rate_limit!(key, ttl)
       redis_conn.get(blocked_key).should_not be_nil
       redis_conn.ttl(blocked_key).should == ttl
     end
@@ -65,8 +65,8 @@ describe Pause::Redis::Adapter do
     let(:ttl) { 110000 }
 
     it "should return true if blocked" do
-      adapter.block(key, ttl)
-      (!!redis_conn.get(blocked_key).should) == adapter.blocked?(key)
+      adapter.rate_limit!(key, ttl)
+      (!!redis_conn.get(blocked_key).should) == adapter.rate_limited?(key)
     end
   end
 

data/spec/spec_helper.rb

@@ -9,8 +9,7 @@ ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
 require 'rubygems'
 require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE'])
 require 'pause'
-
-Dir['spec/support/**/*.rb'].each { |filename| require_relative "../#{filename}" }
+require 'support/fakeredis'
 
 RSpec.configure do |config|
   config.treat_symbols_as_metadata_keys_with_true_values = true

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pause
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
 - Atasay Gokkaya
 - Paul Henry
-- Eric Saxny
+- Eric Saxby
 autorequire: 
 bindir: bin
 cert_chain: []
@@ -122,6 +122,7 @@ files:
 - .pairs
 - .rspec
 - .rvmrc
+- .travis.yml
 - Gemfile
 - Guardfile
 - LICENSE.txt
@@ -130,9 +131,9 @@ files:
 - lib/pause.rb
 - lib/pause/action.rb
 - lib/pause/analyzer.rb
-- lib/pause/blocked_action.rb
 - lib/pause/configuration.rb
 - lib/pause/helper/timing.rb
+- lib/pause/rate_limited_event.rb
 - lib/pause/redis/adapter.rb
 - lib/pause/version.rb
 - pause.gemspec
@@ -173,4 +174,3 @@ test_files:
 - spec/pause/redis/adapter_spec.rb
 - spec/spec_helper.rb
 - spec/support/fakeredis.rb
-has_rdoc: