merb_threshold

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]