merb_threshold
==============

Merb Threshold provides an easy way to apply control the number of times something is done in a merb
app, this includes dispatching to actions, rendering partials, etc.

Thresholds can be applied to multiple partials per page and can even span controllers and actions.

Also all of the methods are pretty well documented, so it might be pretty helpful to look at the method documentation.

When a threshold is exceeded it can be relaxed either by captcha or waiting, depending on the partial that is rendered.

==== Set up

# Add to init.rb
require 'merb_threshold'

Merb::Plugins.config[:merb_threshold] = {
  :public_key           => nil,    # Recaptcha Public Key
  :private_key          => nil,   # Recaptcha Private Key
  :recaptcha            => true,  # Enable Recaptcha

  # Only needed if using Merb::Threshold::Helpers
  # both take :partial as an option to specify an alternate partial
  # wait() 
  # wait(:partial => "shared/other_wait_partial")
  #
  :wait_partial         => 'shared/wait_partial',       #Path to default partial
  :captcha_partial      => 'shared/recaptcha_partial'    #Path to default partial
}


# Two helpers are included: captcha() and wait()
#   The helpers aren't needed (see API) below, and are just provided as two examples
#   of how to use the API to render wait and captch partials
#
class Merb::Controller
  include Merb::Threshold::Helpers
end


==== Public API
  Thresholds are shared across controllers, which makes it possible to do things like
  display a shared login partial in your Home controller while your Authentication controller
  manages the access.
  
  Instance Methods
  * Merb::Controller#permit_access?          
    - is access permitted to the resources   
    - Takes a threshold name
  * Merb::Controller#will_permit_another?   
    - will the threshold permit another request.  
    - Takes threshold name
  * Merb::Controller#is_currently_exceeded? 
    - is the threshold currently exceeded (may have been exceeded by a previous request)
    - Take threshold name
  
  Class Methods
  * Merb::Controller.register_threshold     - registers a threshold, all thresholds must be 'registered'  
  * Merb::Controller.threshold_actions       - This is a helper method.  It registers the thresholds automatically
      and creates before filters to check permit_access?.  If no actions are listed thresholds, are maintained
      on the controller itself (shared between actions).  Optionally a list of action names can be given and an
      threshold will be created for each one.
      
  If you are not keen of the names generated by
  

==== Thresholding at the Controller / Action level
  
  Action based thresholding allows for controlling access to an action as a whole.  The class level 'threshold' method
  is actually just a wrapper around a before filter that calls the instances level threshold.  Providing the
  wrapper does allow for the threshold to halt the filter chain.  
    
  Example:
    class MyController < Application
      threshold_actions :index, :create, :limit => [5, 30.seconds]
    
      #equivalent to:
      register_threshold :"my_controller/index", :limit => [5, 30.seconds]
      before(nil,{:only => [:index]}) do
        permit_access? :"my_controller/index"
      end
       
      register_threshold :"my_controller/create", :limit => [5, 30.seconds]
      before(nil,{:only => [:create]}) do
        permit_access? :"my_controller/create"
      end
    
    #create a controller level threshold
    class MyController < Application
      threshold_actions :limit => [5000, 1.day]
        
      #equivalent to:
      register_threshold :my_controller, :limit => [5000, 1.day]
      before(nil,{}) do
        permit_access? :my_controller
      end
    
    #create 1 action level threshold with :unless statement and halt
    class MyController < Application
      threshold_actions :search, :limit => [10, 5.minutes], 
        :unless => :is_admin?, 
        :halt_with => "Too many searches"
    
      #equivalent to:
      register_threshold :"my_controller/search", :limit => [10, 5.minutes]
      before(nil,{:only => [:search], :unless => :is_admin?}) do
        if !permit_access?(:"my_controller/search")
          throw(:halt, "Too many searches")
        end
      end
  
==== Partial / View based thresholding

  Partial / View based thresholding can take advantage of action based thresholds or named thresholds.
  class Whatever < Application
    register_threshold :stuff_to_protect, :limit => 1.per(3.minutes)
  # --- apps/views/whatever/index.html.erb
  <!--
    Cool html stuff
  -->
  <% if permit_access? :stuff_to_protect %>
    <!-- Show your stuff, access wasn't thresholded -->
    <div> Coolness?! </div>
  <% else %>
    <%= wait(:stuff_to_protect) %>
    <!-- your users gets a wait message -->
  <% end %>
  
==== Cross Controller/Action thresholding

  Using named thresholds it is possible to control a threshold across several controllers, actions, and partials.
  
  Thresholds are shared across all controllers that extend from Merb::Controller, so a threshold can be accessed
  by any controller, and more importantly partials can be rendered for thresholds in other controllers
  
  Just like in 'Partial / View based thresholding' theses three methods can be used to control the flow of what
  is rendered.
  
  Methods:
    * permit_access?          - Returns True|False, was the request OVER the threshold
    * will_permit_another?     - Will the threshold permit another request
    * is_currently_exceeded?   - Is the current request over the threshold
  
  Helpers (Override at your leisure in Merb::Threshold::Helpers)
    * wait(threshold_name)     - displays the wait message
    * captcha(threshold_name) - displays the captcha
  

=== Threshold Names vs Threshold Keys

  * A threshold name is used as the identifier so the controller can keep track of registered options
  * A threshold key is how to look up a particular threshold's data in the user's session
  
  Threshold keys should be used whenever accessing any of the data stored in the users' session.

=== Clearing / Destroying sessions
  
  Since all merb_threshold data is stored in the session clearing or destroying the session will remove
  any data stored for that session.  This becomes important if you clear session on logout, because it 
  essentially resets the access history for a user.  To get around this simply copy out the merb_threshold
  data before clearing/destroy and then put it back in the new 'anonymous' session afterwards.  This applies
  to logins if they clear/destroy the anonymous session before presenting the authenticated one.
  
  You could do something like this or whatev.
  def logout
    clear_keys = session.keys - [
      'merb_threshold_history',
      'merb_threshold_exceeded_thresholds',
      'merb_threshold_waiting_period']

    session.regenerate
    clear_keys.each { |k| session.delete(k) }
  end


=== will_permit_another? vs is_currently_exceeded?

  *  will_permit_another?
    * Note: takes a threshold_name
    * determines if an immediate subsequent request would exceed the threshold
    * Suggested Use: when one request 'protects' another
      * Example: A GET request that retrieved a form could protect the subsequent POST request
    
  *  is_currently_exceeded?
    * Note: takes a threshold_name
    * determines if the current request is in over the threshold
    * Suggested Use: when throttling the amount of requests a resource gets
      * Example: An API that allows X amount of free accesses before display a 'please pay me' page

==== A case for will_permit_another?

  * A sign up page has a limit of 5 signups per minute.
  * A user signs up 5 accounts in a row (w/ no captcha | wait)
  * On the sixth GET of the form the request's call to captcha() determines another request will exceeded the threshold, 
  so a captcha is presented
  
==== A case for will_permit_another?

  * A user is promised access to a free API 5000 times per day
  * The user's app makes 5000 requests
  * On the 5001 request is_currently_exceeded? could be used to render an 'over the limit' partial


=== Misc. Notes

 * Thresholds can be named whatever you want, so they can be programmatically created.  Also
  the option :params => [:blog_id,:etc] is available that will use param values as part of the key
    
 * merb_threshold currently stores everything in the session (may have support for)
    additional stores in the future.  On that note, it is not recommended to be used
    with cookie base sessions because it could be easy for a user to go over 4k worth
    of data if the site is composed of many controllers, actions, and partials

 * A threshold is EXCEEDED when it goes beyond its limit
     Given:
      register_threshold :index, :limit => [3,30.seconds]
    The threshold would be considered EXCEEDED on its 4th request.
        
 * Time.now is used for all times since access times are relative
    The frequency class could be a lot more useful if it didn't explicitly use Time.now and you could
    look forward and backward over time.  Fortunately that complexity isn't needed for actions because
    you are accessing them 'now' and the plugin is concerned with 'when' they were last accessed.
    
 * If you dont like the way units are cast using :limit => [1,30.minutes]
    You can override Frequency#cast_units OR specify :limt => [1,30,:minutes]