pause 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6c71d4ddaa7df30afce53ce0c5f9cb355326d8f8
-  data.tar.gz: 6ab9fbd9854b7d970bffc0e6436ca788f7303ac5
+SHA256:
+  metadata.gz: 81a777526619b80e87ad3e11b6794c88634ea326cf34aad34ac70268517cdf4f
+  data.tar.gz: 17f95640fde2ddd98e6922b7cab715e8c7973b791a3e728c65f132265da55b78
 SHA512:
-  metadata.gz: 6960d06f4e402f5f45c8f4c731db11783bce91aa0ba1e3910a41b5ef2a5c75d5365645b32d7a712c0607dfc41c943db489db9ef89f5932a8ceebefd1addaefc3
-  data.tar.gz: 7a6b55e41e5cab30e2d586a190ca7cb12c7a4de691aba0c5698693418d427c9793b33d92d3d70125fdd71d5b6b9dbc92dc7a1bdd517f74e6178386d600983556
+  metadata.gz: f46245fe1330897e8bf6dee18d32b8cc561849f59d5c6049bd45360b5614d27a7f0e0caf8494e93cd6266a733750cdd3aad2559508364c9ee7990493fb0934de
+  data.tar.gz: c9fc4e23661001591aac93c7427e9e98ac03e6d5e15da060c537f43ce47b1eca3ac65658004ffff7e5706a59b1c98e7b7236329c1cd722e4348f2741acbd5e8c

data/.gitignore

@@ -17,3 +17,5 @@ test/version_tmp
 tmp
 .idea
 .DS_Store
+.ruby-version
+.spec

data/.travis.yml

@@ -1,10 +1,14 @@
 language: ruby
 rvm:
-  - 1.9.3
-script: "bundle exec rspec"
+  - 2.3.3
+  - 2.4.3
+  - 2.5.0
+script: "bundle exec rake || ( sleep 1; bundle exec rspec --only-failures ) "
+services:
+  - redis-server
 notifications:
   email:
     recipients:
-      - dev-info@wanelo.com
+      - kigster@gmail.com
     on_success: never
     on_failure: always

data/Gemfile

@@ -5,11 +5,3 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in pause.gemspec
 gemspec
-
-gem 'fakeredis'
-gem 'guard-rspec'
-gem 'pry-nav'
-gem 'rake'
-gem 'rb-fsevent'
-gem 'rspec'
-gem 'timecop'

data/README.md

@@ -1,17 +1,105 @@
-Pause
-======
+# Pause
 
 [![Gem Version](https://badge.fury.io/rb/pause.png)](http://badge.fury.io/rb/pause)
-[![Build status](https://secure.travis-ci.org/wanelo/pause.png)](http://travis-ci.org/wanelo/pause)
+[![Build Status](https://travis-ci.org/kigster/pause.svg?branch=master)](https://travis-ci.org/kigster/pause)
 
-Pause is a flexible Redis-backed rate-limiting client. Use it to track events, with
+## In a Nutshell
+
+**Pause** is a fast and very flexible Redis-backed rate-limiter. You can 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:
+ 
+ * throttling notifications sent to a user as to not overwhelm them with too much frequency,
+ * IP-based blocking based on HTTP request volume (see the related gem [spanx](https://github.com/wanelo/spanx)) that uses Pause,
+ * ensuring you do not exceed API rate limits when calling external web APIs.
+ * etc.
+ 
+Pause currently does not offer a CLI client, and can only be used from within a Ruby application.
+
+Additionally:
+
+ * Pause is pure-ruby gem and does not depend on Rails or Rack
+ * Pause can be used across multiple ruby processes, since it uses a distributed Redis backend
+ * Pause is currently in use by a web application receiving 6K-10K web requests per second
+ * Pause will work with a horizontally sharded multi-Redis-backend by using Twitter's [Twemproxy](https://github.com/twitter/twemproxy). This way, millions of concurrent users can be handled with ease.
+
+### Quick Start
+
+This section is meant to give you a rapid introduction, so that you can start using Pause immediately.
+
+Our use case: we want to rate limit notifications sent to users, identified by their `user_id`, to:
+
+ * no more than 1 in any 2-hour period
+ * no more than 3 per day
+ * no more than 7 per week
+
+Here is how we could set this up using Pause:
+
+#### Configuration
+
+We need to setup Pause with a Redis instance. Here is how we do it:
+
+```ruby
+require 'pause'
+
+# First, lets point Pause to a Redis instance
+Pause.configure do |config|
+  # Redis connection parameters
+  config.redis_host = '127.0.0.1'
+  config.redis_port = 6379
+  config.redis_db   = 1
+  
+  # aggregate all events into 10 minute blocks. 
+  # Larger blocks require less RAM and CPU, smaller blocks are more 
+  # computationally expensive.
+  config.resolution = 600
+       
+  # discard all events older than 1 day
+  config.history    = 86400   
+end
+```
+
+#### Define Rate Limited "Action"
+
+Next we must define the rate limited action based on the specification above. This is how easy it is:
+
+```ruby
+module MyApp
+  class UserNotificationLimiter < ::Pause::Action
+    # this is a redis key namespace added to all data in this action
+    scope 'un'  
+    check period_seconds:       120, max_allowed: 1
+    check period_seconds:     86400, max_allowed: 3
+    check period_seconds: 7 * 86400, max_allowed: 7
+  end
+end
+```
+
+#### Perform operation, but only if the user is not rate-limited
+
+Now we simply instantiate this limiter by passing user ID (any unique identifier works). We can then ask the limiter, `ok?` or `rate_limited?`, or we can use two convenient methods that only execute enclosed block if the described condition is satisfied:
+
+```ruby
+class NotificationsWorker
+  def perform(user_id)
+    limiter = MyApp::UserNotificationLimiter.new(user_id)
+    
+    limiter.unless_rate_limited do
+      user = User.find(user_id) 
+      user.send_push_notification!
+    end
+    
+    # You can also do something in case the user is rate limited:
+    limiter.if_rate_limited do |rate_limit_event|
+      Rails.logger.info("user #{user.id} has exceeded rate limit: #{rate_limit_event}") 
+    end
+  end
+end
+```
+
+That's it! Using these two methods you can pretty much ensure that your rate limits are always in check. 
 
-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
 
@@ -86,47 +174,44 @@ In other words, if your shortest check is 1 minute, you could set resolution to
 require 'pause'
 
 class FollowAction < Pause::Action
-  scope "f"
+  scope 'fa' # keep those short
   check period_seconds:   60, max_allowed:  100, block_ttl: 3600
   check period_seconds: 1800, max_allowed: 2000, block_ttl: 3600
 end
 ```
 
-When an event occurs, you increment an instance of your action, optionally with a timestamp and count. This saves
-data into a redis store, so it can be checked later by other processes. Timestamps should be in unix epoch format.
+When an event occurs, you increment an instance of your action, optionally with a timestamp and count. This saves data into a redis store, so it can be checked later by other processes. Timestamps should be in unix epoch format.
+
+In the example at the top of the README you saw how we used `#unless_rate_limited` and `#if_rate_limited` methods. These are the recommended API methods, but if you must get a finer-grained control over the actions, you can also use methods such as `#ok?`, `#rate_limited?`, `#increment!` to do manually what the block methods do already. Below is an example of this "manual" implementation:
 
 ```ruby
 class FollowsController < ApplicationController
   def create
     action = FollowAction.new(user.id)
     if action.ok?
-      # do stuff!
-      # and track it...
+      user.follow! 
+      # and don't forget to track the "success"
       action.increment!
-    else
-      # action is rate limited, either skip
-      # or show error, depending on the context.
     end
   end
 end
 
 class OtherController < ApplicationController
   def index
-    action = OtherAction.new(params[:thing])
+    action = OtherAction.new(params[:thing])d
     unless action.rate_limited?
       # perform business logic
-      ....
-      # track it
+      # but in this
       action.increment!(params[:count].to_i, Time.now.to_i)
     end
   end
 end
 ```
 
-If more data is needed about why the action is blocked, the `analyze` can be called
+If more data is needed about why the action is blocked, the `analyze` can be called:
 
 ```ruby
-action = NotifyViaEmailAction.new("thing")
+action = NotifyViaEmailAction.new(:thing)
 
 while true
   action.increment!
@@ -222,6 +307,26 @@ tracked identifiers.
 
 The action block list is implemented as a sorted set, so it should still be usable when sharding.
 
+## Testing
+
+By default, `fakeredis` gem is used to emulate Redis in development. However, the same test-suite should be able to run against a real redis — however, be aware that it will flush the current db during spec run. In order to run specs against real redis, make sure you have Redis running locally on the default port, and that you are able to connect to it using `redis-cli`.
+
+Please note that Travis suite, as well as the default rake task, run both.
+
+### Unit Testing with Fakeredis
+
+Fakeredis is the default, and is also run whenever `bundle exec rspec` is executed, or `rake spec` task invoked.
+
+```bash
+bundle exec rake spec:unit
+```
+
+### Integration Testing with Redis
+
+```bash
+bundle exec rake spec:integration
+```
+
 ## Contributing
 
 Want to make it better? Cool. Here's how:

data/Rakefile

@@ -1,6 +1,47 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task :default => %w(spec:unit spec:integration)
+
+namespace :spec do
+  desc 'Run specs using fakeredis'
+  task :unit do
+    ENV['PAUSE_REAL_REDIS'] = nil
+    Rake::Task['spec'].execute
+  end
+  desc 'Run specs against a local Redis server'
+  task :integration do
+    ENV['PAUSE_REAL_REDIS'] = 'true'
+    Rake::Task['spec'].execute
+  end
+end
+
+def shell(*args)
+  puts "running: #{args.join(' ')}"
+  system(args.join(' '))
+end
+
+task :clean do
+  shell('rm -rf pkg/ tmp/ coverage/ doc/ ' )
+end
+
+task :gem => [:build] do
+  shell('gem install pkg/*')
+end
+
+task :permissions => [ :clean ] do
+  shell('chmod -v o+r,g+r * */* */*/* */*/*/* */*/*/*/* */*/*/*/*/*')
+  shell("find . -type d -exec chmod o+x,g+x {} \\;")
+end
+
+task :build => :permissions
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = %w(lib/**/*.rb exe/*.rb - README.md LICENSE.txt)
+  t.options.unshift('--title','"Pause - Redis-backed Rate Limiter"')
+  t.after = ->() { exec('open doc/index.html') }
+end
+

data/lib/pause.rb

@@ -37,11 +37,11 @@ module Pause
     end
 
     def configure(&block)
-      @configuration = Pause::Configuration.new.configure(&block)
+      @configuration ||= Pause::Configuration.new.configure(&block)
     end
 
-    def config
-      @configuration
+    def config(&block)
+      configure(&block)
     end
   end
 end

data/lib/pause/action.rb

@@ -3,60 +3,127 @@ module Pause
     attr_accessor :identifier
 
     def initialize(identifier)
-      @identifier = identifier
-      self.class.checks = [] unless self.class.instance_variable_get(:@checks)
+      @identifier       = identifier
+      self.class.checks ||= []
     end
 
-    # Action subclasses should define their scope as follows
-    #
-    #     class MyAction < Pause::Action
-    #       scope "my:scope"
-    #     end
-    #
     def scope
-      raise 'Should implement scope. (Ex: ipn:follow)'
-    end
-
-    def self.scope(scope_identifier = nil)
-      class_variable_set(:@@class_scope, scope_identifier)
-      define_method(:scope) { scope_identifier }
-    end
-
-    # 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.
-    #  block_ttl      - time to mark identifier as not ok
-    #
-    #     class MyAction < Pause::Action
-    #       check period_seconds: 60,   max_allowed: 100,  block_ttl: 3600
-    #       check period_seconds: 1800, max_allowed: 2000, block_ttl: 3600
-    #     end
-    #
-    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
+      self.class.scope
+    end
+
+    class << self
+      attr_accessor :checks
+
+      def inherited(klass)
+        klass.instance_eval do
+          # Action subclasses should define their scope as follows
+          #
+          #     class MyAction < Pause::Action
+          #       scope "my:scope"
+          #     end
+          #
+          @scope = klass.name.downcase.gsub(/::/, '.')
+          class << self
+
+            # @param [String] args
+            def scope(*args)
+              @scope = args.first if args && args.size == 1
+              @scope
+            end
+          end
         end
-      @checks << Pause::PeriodCheck.new(period_seconds, max_allowed, block_ttl)
-    end
-
-    def self.checks
-      @checks
+      end
+
+      # Actions can be globally disabled or re-enabled in a persistent
+      # way.
+      #
+      #   MyAction.disable
+      #   MyAction.enabled? => false
+      #   MyAction.disabled? => true
+      #
+      #   MyAction.enable
+      #   MyAction.enabled? => true
+      #   MyAction.disabled? => false
+      #
+      def enable
+        adapter.enable(scope)
+      end
+
+      def disable
+        adapter.disable(scope)
+      end
+
+      def enabled?
+        adapter.enabled?(scope)
+      end
+
+      def disabled?
+        !enabled?
+      end
+
+      # 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.
+      #  block_ttl      - time to mark identifier as not ok
+      #
+      #     class MyAction < Pause::Action
+      #       check period_seconds: 60,   max_allowed: 100,  block_ttl: 3600
+      #       check period_seconds: 1800, max_allowed: 2000, block_ttl: 3600
+      #     end
+      #
+      def check(*args, **opts)
+        self.checks ||= []
+
+        params =
+          if args.empty?
+            # if block_ttl is not provided, just default to the period
+            opts[:block_ttl] ||= opts[:period_seconds]
+            [opts[:period_seconds], opts[:max_allowed], opts[:block_ttl]]
+          else
+            args
+          end
+
+        self.checks << Pause::PeriodCheck.new(*params)
+      end
+
+      def tracked_identifiers
+        adapter.all_keys(scope)
+      end
+
+      def rate_limited_identifiers
+        adapter.rate_limited_keys(scope)
+      end
+
+      def unblock_all
+        adapter.delete_rate_limited_keys(scope)
+      end
+
+      def adapter
+        Pause.adapter
+      end
+    end
+
+    def unless_rate_limited(count: 1, timestamp: Time.now.to_i, &_block)
+      check_result = analyze
+      if check_result.nil?
+        yield
+        increment!(count, timestamp)
+      else
+        check_result
+      end
+    end
+
+    def if_rate_limited(&_block)
+      check_result = analyze(recalculate: true)
+      yield(check_result) unless check_result.nil?
     end
 
     def checks
       self.class.checks
     end
 
-    def self.checks=(period_checks)
-      @checks = period_checks
-    end
-
     def block_for(ttl)
       adapter.rate_limit!(scope, identifier, ttl)
     end
@@ -66,7 +133,7 @@ module Pause
     end
 
     def rate_limited?
-      ! ok?
+      !ok?
     end
 
     def ok?
@@ -76,65 +143,19 @@ module Pause
       false
     end
 
-    def analyze
-      Pause.analyzer.check(self)
-    end
-
-    def self.tracked_identifiers
-      adapter.all_keys(self.class_scope)
-    end
-
-    def self.rate_limited_identifiers
-      adapter.rate_limited_keys(self.class_scope)
-    end
-
-    def self.unblock_all
-      adapter.delete_rate_limited_keys(self.class_scope)
+    def analyze(recalculate: false)
+      Pause.analyzer.check(self, recalculate: recalculate)
     end
 
     def unblock
       adapter.delete_rate_limited_key(scope, identifier)
     end
 
-    # Actions can be globally disabled or re-enabled in a persistent
-    # way.
-    #
-    #   MyAction.disable
-    #   MyAction.enabled? => false
-    #   MyAction.disabled? => true
-    #
-    #   MyAction.enable
-    #   MyAction.enabled? => true
-    #   MyAction.disabled? => false
-    #
-    def self.enable
-      adapter.enable(class_scope)
-    end
-
-    def self.disable
-      adapter.disable(class_scope)
-    end
-
-    def self.enabled?
-      adapter.enabled?(class_scope)
-    end
-
-    def self.disabled?
-      ! enabled?
-    end
-
     private
 
-    def self.adapter
-      Pause.adapter
-    end
-
     def adapter
       self.class.adapter
     end
 
-    def self.class_scope
-      class_variable_get:@@class_scope if class_variable_defined?(:@@class_scope)
-    end
   end
 end