merb_threshold 0.1.4

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Cory ODaniel
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+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.

data/README

@@ -0,0 +1,225 @@
+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]

data/Rakefile

@@ -0,0 +1,62 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+
+require 'spec/rake/spectask'
+require "rake/testtask"
+
+require "spec"
+require "spec/rake/spectask"
+
+require 'merb-core'
+require 'merb-core/tasks/merb'
+
+GEM_NAME = "merb_threshold"
+GEM_VERSION = "0.1.4"
+AUTHOR = "Cory O'Daniel"
+EMAIL = "contact@coryodaniel.com"
+HOMEPAGE = "http://github.com/coryodaniel"
+SUMMARY = "Merb plugin that provides resource access rate limits and captcha'ing"
+
+Dir['tasks/**/*.rb'].each do |f|
+  puts f
+  require f
+end
+
+spec = Gem::Specification.new do |s|
+  s.rubyforge_project = 'merb'
+  s.name = GEM_NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "LICENSE", 'TODO']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  s.add_dependency('merb', '>= 1.0.7.1')
+  s.require_path = 'lib'
+  s.files = %w(LICENSE README Rakefile TODO) + Dir.glob("{lib,spec}/**/*")
+  
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "install the plugin as a gem"
+task :install do
+  Merb::RakeHelper.install(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Uninstall the gem"
+task :uninstall do
+  Merb::RakeHelper.uninstall(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Create a gemspec file"
+task :gemspec do
+  File.open("#{GEM_NAME}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end

data/TODO

@@ -0,0 +1,4 @@
+TODO:		
+	* Consider adding ability to have various stores for threshold data
+	* Consider HTTP method option to threshold
+	* Support for MerbParts

data/lib/merb_threshold.rb

@@ -0,0 +1,35 @@
+if defined?(Merb::Plugins)  
+  Merb::Plugins.config[:merb_threshold] = {
+    :public_key           => nil,
+    :private_key          => nil,
+    :recaptcha            => true,
+    :wait_partial         => 'shared/wait_partial',
+    :captcha_partial      => 'shared/recaptcha_partial'
+  }
+          
+  module Merb
+    module Threshold
+    end
+  end
+  
+  require 'merb-helpers/time_dsl'
+  
+  require "merb_threshold/frequency"
+  require "merb_threshold/per"
+  require "merb_threshold/controller/merb_controller"
+  require "merb_threshold/helpers/wait_helper"  
+  
+  Numeric.send :include, Merb::Threshold::Per
+  include Merb::Threshold
+  
+  Merb::Plugins.add_rakefiles "merb_threshold/merbtasks"
+  
+  Merb::BootLoader.before_app_loads do
+    if Merb::Plugins.config[:merb_threshold][:recaptcha]
+      require 'merb_threshold/recaptcha_client'
+      require 'merb_threshold/helpers/recaptcha_helper'
+      RecaptchaClient.public_key  = Merb::Plugins.config[:merb_threshold][:public_key]
+      RecaptchaClient.private_key = Merb::Plugins.config[:merb_threshold][:private_key]
+    end
+  end
+end

data/lib/merb_threshold/controller/merb_controller.rb

@@ -0,0 +1,452 @@
+module Merb
+  class Controller
+    THRESHOLD_OPTIONS = [:limit, :params]
+    THRESHOLD_DEFAULTS = {
+      :limit      => [0,0.seconds],  #[Access, PerSecond]
+      :params     => nil            #[:list, :of, :params, :to, :use, :in, :key]
+    }
+    
+    #Use to keep an index of thresholds for looking up information
+    # by name
+    @@_threshold_map = Mash.new
+    
+    class << self
+      ##
+      # Registers a threshold for tracking
+      #
+      # @param threshold_name [~Symbol] name of threshold
+      #
+      # @param opts [Hash] Options on how to enforce threshold
+      #   * :params     [Array[~Symbol]] Parameters to include in the threshold key
+      #     :params => [:blog_id]
+      #
+      #   * :limit    [Array[Fixnum,Fixnum,Symbol]] number of access per time interval before
+      #               threshold constraints are applied
+      #               Default [0,0.seconds] #Always
+      #     :limit => [2,5,:minutes]            #=> Frequency(2,5,:minutes)   2 per 5 minutes
+      #     :limit => [1, 5.minutes]          #=> Frequency(1,5.minutes)   1 per 5 minutes
+      #
+      # @raises ArgumentError
+      #
+      # @api public
+      #
+      # @return [Array[~Symbol,Hash]]
+      #   The name, opts it was registered as
+      def register_threshold(threshold_name,opts={})
+        if threshold_name.is_a?(Hash)
+          raise ArgumentError, "Thresolds must be named!"
+        end
+
+        opts = THRESHOLD_DEFAULTS.merge(opts)
+
+        opts.each_key do |key| 
+          raise(ArgumentError,
+            "You can only specify known threshold options (#{THRESHOLD_OPTIONS.join(', ')}). #{key} is invalid."
+          ) unless THRESHOLD_OPTIONS.include?(key)
+        end
+
+        #register it
+        @@_threshold_map[threshold_name] = opts
+      end
+      
+      ##
+      # A succinct wrapper to bulk register thresholds on actions and check access to those thresholds
+      # in before filters.  This method will register the threshold and create the before filters.
+      # 
+      # The threshold names will be "#{controlLer_name}/#{action_name}" when actions are given.
+      #
+      # If not actions are specified the threshold will be named for the controller.
+      #
+      # @param *args [~Array]
+      #   args array for handling array of action names and threshold options
+      #   Threshold queues are keyed with the controller & action name, so each
+      #   action will have its own queue
+      #
+      # @param opts [Hash]
+      #   * :limit    [Array[Fixnum,Fixnum,Symbol]] number of access per time interval before
+      #               threshold constraints are applied
+      #               Default [0,0.seconds] #Always
+      #     :limit => [2,5,:minutes]            #=> Frequency(2,5,:minutes)   2 per 5 minutes
+      #     :limit => [1, 5.minutes]          #=> Frequency(1,5.minutes)   1 per 5 minutes
+      #
+      #   * :halt_with  [String,Symbol,Proc] Halts the filter chain instead if the
+      #                 threshold is in effect
+      #                 takes same params as before filter's throw :halt
+      #                 not specifying :halt_with when the mode is :halt
+      #                 will result in: throw(:halt)
+      #
+      #   * :params     [Array[~Symbol]] Parameters to include in the threshold key
+      #     :params => [:blog_id]
+      #                 
+      #   * :if / :unless - Passed to :if / :unless on before filter
+      #
+      # @note
+      #   using the class method threshold_actions registers the threshold 
+      #   (no need for a register_threshold statement) and creates a before filter
+      #   for the given actions where the actual threshold check will take place
+      #
+      # @example
+      #   Using threshold and the before filter it creates:
+      # 
+      #   #Create two action level thresholds
+      #   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    
+      #
+      # @api public
+      #
+      def threshold_actions(*args)
+        opts = args.last.is_a?(Hash) ? args.pop : {}
+        thresholds_to_register = args
+
+        #exctract :limit, :params
+        threshold_opts  = {}
+        threshold_opts[:limit]      = opts.delete(:limit) || [0, 0.seconds] #Always
+        threshold_opts[:params]     = opts.delete(:params)
+
+        halt_with                   = opts.delete(:halt_with)
+
+        #get threshold supported before filter options
+        filter_opts = {}
+        filter_opts[:if]            = opts.delete(:if)      if opts[:if]
+        filter_opts[:unless]        = opts.delete(:unless)  if opts[:unless]
+
+        if thresholds_to_register.empty?
+          # Register a controller level threshold
+          self.register_threshold(controller_name,threshold_opts)
+
+          self.before(nil,filter_opts) do
+            if !permit_access?(controller_name) && halt_with
+              throw(:halt, halt_with)
+            end
+          end
+        else
+          #register a threshold for each action given
+          thresholds_to_register.each do |action_to_register|
+            tmp_threshold_name = "#{controller_name}/#{action_to_register}".to_sym
+            
+            self.register_threshold(tmp_threshold_name,threshold_opts)
+
+            self.before(nil, filter_opts.merge({:only => [action_to_register]})) do 
+              if !permit_access?(tmp_threshold_name) && halt_with
+                throw(:halt,halt_with)
+              end
+            end
+          end
+        end
+      end
+    
+    end #end class << self
+
+
+    ##
+    # Used for determining if a subsequent request would exceed the threshold
+    #   
+    # Good for protecting a post with a form or display captcha/wait before
+    #   the threshold is exceeded
+    #
+    # @note See READEME: will_permit_another? vs is_currently_exceeded?
+    #
+    # @param threshold_name [~Symbol] The threshold to look up
+    #
+    # @api public
+    #
+    # @param [Boolean]
+    def will_permit_another?(threshold_name=nil)
+      threshold_name ||= action_name
+      opts = @@_threshold_map[threshold_name]
+      curr_threshold_key = threshold_key(threshold_name)
+
+      # if opts[:limit] is not set that means the threshold hasn't been registered yet
+      #   so permit access, the threshold will be registered once threshold() is called
+      #   which is usually behind the post request this would be submitted to.
+      if opts[:limit]
+        frequency = if opts[:limit].is_a?(Array)
+          Frequency.new(*opts[:limit])
+        else
+          opts[:limit].clone
+        end
+        frequency.load! access_history(curr_threshold_key)
+    
+        frequency.permit?
+      else
+        true
+      end
+    end
+    
+    ##
+    # Is the threshold currenlty exceeded either by this request or a previous one
+    #
+    # Good for redirecting access during the current request
+    #
+    # @note See READEME: will_permit_another? vs is_currently_exceeded?
+    #
+    # @param threshold_name [~Symbol]
+    #   current threshold key to lookup
+    #
+    # @api public
+    #
+    # @return [Boolean]
+    def is_currently_exceeded?(threshold_name=nil)
+      threshold_name ||= action_name
+      curr_threshold_key = threshold_key(threshold_name)
+      exceeded_thresholds.member? curr_threshold_key
+    end
+    
+    
+    ##
+    # Shortcut to session[:merb_threshold_waiting_period]
+    #
+    # @note
+    #   values stored in here are keyed with #threshold_key
+    #   waiting_period[your_threshold_name] is not guaranteed to work instead use
+    #   waiting_period[threshold_key(your_threshold_name)]
+    #
+    # @see #threshold_key
+    #
+    # @api semi-public
+    #
+    # @return [Hash]
+    def waiting_period
+      session[:merb_threshold_waiting_period] ||= {}
+    end
+        
+    ##
+    # get the key representation of the threshold name.  Used to store data
+    #   in session.  This should be used whenever accessing data stored in the session
+    #   hash.
+    #
+    # @note
+    #   This is needed to support Params values as a part of the threshold name
+    #
+    # @param threshold_name [~Symbol] name of the threshold to get key for
+    #
+    # @api semi-public
+    #
+    # @return [~Symbol]
+    def threshold_key(threshold_name)  
+      curr_threshold_key = threshold_name.to_s
+
+      # create key to lookup threshold data from users session
+      opts = @@_threshold_map[threshold_name]
+      if opts[:params]
+        opts[:params].each{ |param_key| curr_threshold_key += "/#{params[param_key]}" }
+      end
+      
+      curr_threshold_key.to_sym
+    end
+                
+    ##
+    # Is access permitted to the threshold protected resource.
+    #
+    # @param threshold_name [~Symbol] Name of threshold to monitor
+    #
+    # @api public
+    #
+    # @returns [Boolean] was the access permitted?
+    #
+    def permit_access?(threshold_name=nil)
+      threshold_name ||= "#{controller_name}/#{action_name}".to_sym
+      
+      curr_threshold_key = threshold_key(threshold_name)
+      opts = @@_threshold_map[threshold_name]
+      
+      if opts.nil?
+        raise Exception, "Threshold (#{threshold_name}) was not registered"
+      end
+      
+      # keep track of thresholds access and if they were relaxed
+      @relaxed_thresholds ||= {}
+      @relaxed_thresholds[curr_threshold_key] = false
+          
+      # may or may not be exceeded, but threshold was not relaxed
+      frequency = if opts[:limit].is_a?(Array)
+        Frequency.new(*opts[:limit])
+      else
+        opts[:limit].clone
+      end
+      
+      frequency.load! access_history(curr_threshold_key)
+      
+      # Is this request permitted?
+      if frequency.permit? && !is_currently_exceeded?(threshold_name)
+        # if it is also in the exceeded list
+        access_history(curr_threshold_key) << Time.now.to_i
+        @relaxed_thresholds[curr_threshold_key] = true
+      else
+        # if request wasn't permitted and isn't already marked exceeded, mark it
+        exceeded_thresholds << curr_threshold_key unless is_currently_exceeded?(threshold_name)
+        
+        #set the time until the treshold expires
+        waiting_period[curr_threshold_key] = frequency.wait
+
+        # try to relax threshold via captcha if enabled, then via waiting
+        if Merb::Plugins.config[:merb_threshold][:recaptcha]
+          @relaxed_thresholds[curr_threshold_key] = relax_via_captcha!(curr_threshold_key)
+        end
+        @relaxed_thresholds[curr_threshold_key] ||= relax_via_waiting! curr_threshold_key
+      end
+
+      #Only keep the last n number of access where n is frequency.occurence
+      access_history(curr_threshold_key).replace frequency.current_events  
+      
+      return @relaxed_thresholds[curr_threshold_key]
+    end
+        
+    ##
+    # Looks up the users access history
+    #
+    # @param curr_threshold_key [~Symbol]
+    #   current threshold key to lookup
+    #
+    # @note
+    #   this is a shortcut to the session hash, thus it needs the threshold_key not the 
+    #   threshold_name
+    #
+    # @see #threshold_key
+    #
+    # @api private
+    #
+    # @return [Array[Fixnum]]
+    def access_history(curr_threshold_key)        
+      session[:merb_threshold_history] ||= {}
+      session[:merb_threshold_history][curr_threshold_key] ||= []
+      session[:merb_threshold_history][curr_threshold_key]
+    end
+    
+    ##
+    # Gets a list of exceeded thresholds
+    #
+    # @note
+    #   this is a shortcut to the session hash, thus it needs the threshold_key not the 
+    #   threshold_name
+    #
+    # @see #threshold_key
+    #
+    # @api private
+    #
+    # @return [Array[~Symbol]]
+    #
+    def exceeded_thresholds
+      session[:merb_threshold_exceeded_thresholds] ||= []
+      session[:merb_threshold_exceeded_thresholds]      
+    end
+    
+    protected
+                
+    ##
+    # Determines if the user's request solved the captcha
+    #
+    # If the threshold was relaxed, this method resets exceeded threshold and access history
+    #   for this key
+    #
+    # @param curr_threshold_key [~Symbol]
+    #   current threshold key to lookup
+    #
+    # @note
+    #   this deals primarily with the session hash, thus it needs the threshold_key not the 
+    #   threshold_name
+    #
+    # @see #threshold_key
+    #
+    # @api private
+    #
+    # @return [Boolean]
+    def relax_via_captcha!(curr_threshold_key)
+      if params[:recaptcha_challenge_field] && params[:recaptcha_response_field]
+        did_solve, captcha_error = ::RecaptchaClient.solve(request.remote_ip,
+          params[:recaptcha_challenge_field],
+          params[:recaptcha_response_field]
+        )
+      
+        if did_solve
+          relax_threshold(curr_threshold_key)
+        else
+          @captcha_error = captcha_error
+        end
+      
+        did_solve
+      else #no captcha data provided
+        false
+      end
+    end
+    
+    ##
+    # Determines if the threshold was relaxed by the user waiting
+    #
+    # If the threshold was relaxed, this method resets exceeded threshold, wait time and access history
+    #   for this key
+    #
+    # @param curr_threshold_key [~Symbol]
+    #   current threshold key to lookup
+    #
+    # @note
+    #   this deals primarily with the session hash, thus it needs the threshold_key not the 
+    #   threshold_name
+    #
+    # @see #threshold_key
+    #
+    # @api private
+    #
+    # @return [Boolean]
+    #
+    def relax_via_waiting!(curr_threshold_key)
+      last_access   = access_history(curr_threshold_key).last
+      time_to_wait  = (waiting_period[curr_threshold_key] || 0)
+      
+      #if there was no previous acces, this didn't relax from waiting
+      return false if last_access.nil?
+      
+      did_relax = (Time.now.to_i > (last_access + time_to_wait))
+      
+      relax_threshold(curr_threshold_key) if did_relax
+      
+      did_relax
+    end
+    
+    ##
+    # Resets all tracked attributes on a threshold
+    #
+    # @param curr_threshold_key [~Symbol] they key to clear
+    #
+    def relax_threshold(curr_threshold_key)
+      exceeded_thresholds.delete curr_threshold_key
+      access_history(curr_threshold_key).clear
+      waiting_period.delete(curr_threshold_key)
+    end
+    
+  end # end Merb::Controller
+end # end Merb