action_throttler 0.1.0

data/README.md

@@ -0,0 +1,95 @@
+# Action Throttler
+
+There is also a PHP version (for [Kohana](http://kohanaframework.org/)), see here: http://github.com/fredwu/kthrottler
+
+## Introduction
+
+Action Throttler is an easy to use Rails plugin to quickly throttle application actions based on configurable duration and limit.
+
+Brought to you by [Envato](http://envato.com) and [Wuit](http://wuit.com).
+
+## Features
+
+* Easy to use, easy to configure
+* Lightweight
+* Supports both Rails 2 and 3
+
+## Limitations
+
+* Supports ActiveRecord only
+* Uses Rake instead of Rails Generator for file generation (for compatibility purpose)
+
+## Usage
+
+### Download and install the plugin
+
+#### Rails 2
+
+	script/plugin install http://fredwu@github.com/fredwu/action_throttler.git
+
+#### Rails 3
+
+	rails plugin install http://fredwu@github.com/fredwu/action_throttler.git
+
+### Set up the plugin
+
+To generate the migration file and migrate the database:
+
+	rake action_throttler:migrate
+	rake db:migrate
+
+Or alternatively:
+
+	rake action_throttler:auto_migrate
+
+### Configure the actions
+
+The configuration file is located at `PATH_TO_YOUR_APP/config/initializers/action_throttler.rb`.
+
+The configuration block looks like this:
+
+	ActionThrottler::Actions.add :mail do |action|
+	  action.duration = 1.hour
+	  action.limit    = 10
+	end
+
+You can add as many configuration blocks as you like, just make sure you label them properly (i.e. like `:mail` in the example).
+
+In the example, we are setting the `:mail` action to perform at most <em>10</em> times within <em>1</em> hour duration.
+
+### Register the actions in your app
+
+Now we will need to register the actions so they are recorded in the database.
+
+To simply run an action, in your app (presumably somewhere in the controller), do this:
+
+	ActionThrottler::Actions.run(:mail)
+
+`ActionThrottler::Actions.run` will return `true` or `false` depending on whether or not the action is being throttled.
+
+`ActionThrottler::Actions.run` has an alias `ActionThrottler::Actions.can_run` and a negative alias `ActionThrottler::Actions.cannot_run`.
+
+Typically, we would want to produce feedback to the user when an action is throttled, you can do so by:
+
+	if ActionThrottler::Actions.cannot_run(:mail)
+	  # tell the user that this action is not performed
+	end
+
+`ActionThrottler::Actions.run` also takes an optional `reference` parameter:
+
+	ActionThrottler::Actions.run(:mail, @current_user)
+
+The reference parameter is very useful because we can track and throttle the action based on a reference, such as a user. The parameter accepts a `String`, an `Integer` or an `ActiveRecord` object.
+
+Note that `ActionThrottler::Actions.run` and its aliases will perform the action when possible. If you only want to check to see if an action can be performed, you can do this:
+
+	ActionThrottler::Actions.can_be_run?(:mail, @current_user)
+
+`ActionThrottler::Actions.can_be_run?` returns `true` or `false` without performing the action, and it also has a negative alias, `ActionThrottler::Actions.cannot_be_run?`.
+
+## Author
+
+Copyright (c) 2010 Fred Wu (<http://fredwu.me>), released under the MIT license
+
+* Envato - <http://envato.com>
+* Wuit - <http://wuit.com>

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rake'
+require 'spec/rake/spectask'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc 'Run the specs'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--colour --format progress --loadby mtime --reverse']
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "action_throttler"
+    s.version = "0.1.0"
+    s.summary = "Action Throttler is an easy to use Rails plugin to quickly throttle application actions based on configurable duration and limit."
+    s.description = "Action Throttler is an easy to use Rails plugin to quickly throttle application actions based on configurable duration and limit."
+    s.email = "ifredwu@gmail.com"
+    s.homepage = "http://github.com/fredwu/action_throttler"
+    s.authors = ["Fred Wu"]
+    s.add_dependency("activerecord")
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/action_throttler.gemspec

@@ -0,0 +1,58 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{action_throttler}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Fred Wu"]
+  s.date = %q{2010-08-09}
+  s.description = %q{Action Throttler is an easy to use Rails plugin to quickly throttle application actions based on configurable duration and limit.}
+  s.email = %q{ifredwu@gmail.com}
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    "README.md",
+     "Rakefile",
+     "action_throttler.gemspec",
+     "init.rb",
+     "install.rb",
+     "lib/action_throttler/actions.rb",
+     "lib/action_throttler/config.rb",
+     "lib/action_throttler/model.rb",
+     "lib/tasks/action_throttler.rake",
+     "lib/tasks/initializer/action_throttler.rb",
+     "lib/tasks/migration/create_action_throttler_logs.rb",
+     "lib/tasks/rake_helper.rb",
+     "spec/action_throttler_spec.rb",
+     "spec/spec_helper.rb",
+     "uninstall.rb"
+  ]
+  s.homepage = %q{http://github.com/fredwu/action_throttler}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Action Throttler is an easy to use Rails plugin to quickly throttle application actions based on configurable duration and limit.}
+  s.test_files = [
+    "spec/action_throttler_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activerecord>, [">= 0"])
+    else
+      s.add_dependency(%q<activerecord>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<activerecord>, [">= 0"])
+  end
+end
+

data/init.rb

@@ -0,0 +1,3 @@
+require File.dirname(__FILE__) + "/lib/action_throttler/actions"
+require File.dirname(__FILE__) + "/lib/action_throttler/config"
+require File.dirname(__FILE__) + "/lib/action_throttler/model"

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/action_throttler/actions.rb

@@ -0,0 +1,75 @@
+module ActionThrottler
+  class Actions
+    class << self
+      # Adds an action to the stack
+      # 
+      # @param [Symbol] action the name of the action, must be unique
+      # @param [Block]  block  the configuration block
+      def add(action = nil, &block)
+        @actions ||= {}
+        
+        raise "A name to the ActionThrottler action is required!" if action.nil?
+        
+        config = ActionThrottler::Config.new
+        block.call(config)
+
+        @actions[action] = config.to_hash
+      end
+      
+      # Checks the database to see if an action can be run
+      # 
+      # @param  [Symbol]  action the name of the action to be run
+      # @param  [Mixed]   ref    (optional) the reference object
+      # @return [Boolean]        returns true or false depending on the outcome
+      def can_be_run?(action, ref = "")
+        ::ActionThrottlerLog.all(:conditions => [
+          "scope = ? AND reference = ? AND created_at >= ?",
+          action.to_s,
+          normalise_ref(ref),
+          @actions[action][:duration].ago
+        ]).size < @actions[action][:limit] ? true : false
+      end
+      
+      # @see self::can_be_run?
+      def cannot_be_run?(action, ref = "")
+        not can_be_run?(action, ref)
+      end
+      
+      # Runs an action and registers it in the database
+      # 
+      # @param  [Symbol]  action the name of the action to be run
+      # @param  [Mixed]   ref    (optional) the reference object
+      # @return [Boolean]        returns true or false depending on the outcome
+      def run(action, ref = "")
+        if can_be_run?(action, ref)
+          ::ActionThrottlerLog.create({
+            :scope     => action.to_s,
+            :reference => normalise_ref(ref)
+          })
+        else
+          false
+        end
+      end
+      
+      # @see self::run
+      def can_run(action, ref = "")
+        run(action, ref)
+      end
+      
+      # @see self::run
+      def cannot_run(action, ref = "")
+        ! run(action, ref)
+      end
+      
+      private
+      
+      # Normalises the ref parameter so it can accept more than one type
+      # 
+      # @param [Mixed] ref the ref parameter
+      # @return [String] ref id
+      def normalise_ref(ref)
+        (ref.is_a?(Integer) || ref.is_a?(String)) ? ref.to_s : ref.id.to_s
+      end
+    end
+  end
+end

data/lib/action_throttler/config.rb

@@ -0,0 +1,18 @@
+module ActionThrottler
+  class Config
+    def initialize
+      @config ||= {}
+    end
+    
+    def to_hash
+      @config
+    end
+    
+    def method_missing(key, value)
+      # converts `key=()` methods to `key()`
+      key = key.to_s.sub(/=$/, "").to_sym
+      
+      @config[key] = value
+    end
+  end
+end

data/lib/action_throttler/model.rb

@@ -0,0 +1,2 @@
+class ActionThrottlerLog < ActiveRecord::Base
+end

data/lib/tasks/action_throttler.rake

@@ -0,0 +1,28 @@
+require File.dirname(__FILE__) + "/rake_helper"
+
+module ActionThrottler
+  class Tasks
+    include ActionThrottler::Rake
+    
+    def self.run!
+      namespace :action_throttler do
+        desc "Generates the Action Throttler initializer file"
+        task :init => :environment do
+          copy_initializer_file "The Action Throttler initializer file has been generated."
+        end
+        
+        desc "Generates the Action Throttler database migration file"
+        task :migrate => :init do
+          copy_migration_file "The Action Throttler migration file has been generated."
+        end
+        
+        desc "Generates the Action Throttler database migration file and migrates the database"
+        task :auto_migrate => :migrate do
+          ::Rake::Task["db:migrate"].invoke
+        end
+      end
+    end
+  end
+end
+
+ActionThrottler::Tasks.run!

data/lib/tasks/initializer/action_throttler.rb

@@ -0,0 +1,4 @@
+# ActionThrottler::Actions.add :mail do |action|
+#   action.duration = 1.hour
+#   action.limit    = 10
+# end

data/lib/tasks/migration/create_action_throttler_logs.rb

@@ -0,0 +1,17 @@
+class CreateActionThrottlerLogs < ActiveRecord::Migration
+  def self.up
+    create_table :action_throttler_logs, :force => true do |t|
+      t.string :scope
+      t.string :reference
+      t.timestamps
+    end
+	
+    add_index :action_throttler_logs, :scope
+    add_index :action_throttler_logs, :reference
+    add_index :action_throttler_logs, [:scope, :reference]
+  end
+  
+  def self.down
+    drop_table :action_throttler_logs
+  end
+end

data/lib/tasks/rake_helper.rb

@@ -0,0 +1,55 @@
+require "rails/railties/lib/rails_generator/base"
+require "rails/railties/lib/rails_generator/commands"
+
+module ActionThrottler
+  module Rake
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+    
+    module ClassMethods
+      # Copies the migration file to `db/migrate`
+      # 
+      # @param [String] message optional output message
+      def copy_migration_file(message = "")
+        orig_dir  = "#{File.dirname(__FILE__)}/migration/"
+        orig_file = Dir.entries(orig_dir).last
+        orig_path = orig_dir + orig_file
+        
+        prefix    = Rails::Generator::Commands::Base.new(nil).send(:next_migration_string)
+        dest_path = "db/migrate/#{prefix}_#{orig_file}"
+        
+        copy_file(orig_path, dest_path, message)
+      end
+      
+      # Copies the initializer file to `config/initializers`
+      # 
+      # @param [String] message optional output message
+      def copy_initializer_file(message = "")
+        orig_dir  = "#{File.dirname(__FILE__)}/initializer/"
+        orig_file = Dir.entries(orig_dir).last
+        orig_path = orig_dir + orig_file
+        
+        dest_path = "config/initializers/#{orig_file}"
+        
+        copy_file(orig_path, dest_path, message)
+      end
+      
+      # Copies a file
+      # 
+      # @param [String] orig_path original file path, absolute
+      # @param [String] dest_path destination file path, relative to `Rails.root`
+      # @param [String] message optional output message
+      def copy_file(orig_path, dest_path, message = "")
+        dest_path = "#{Rails.root}/#{dest_path}"
+        
+        if File.exists?(dest_path)
+          puts "'#{dest_path}' already exists, therefore it is skipped."
+        else
+          FileUtils.cp(orig_path, dest_path)
+          puts message unless message.nil?
+        end
+      end
+    end
+  end
+end

data/spec/action_throttler_spec.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + '/spec_helper'

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+begin
+  require File.dirname(__FILE__) + '/../../../../spec/spec_helper'
+rescue LoadError
+  puts "You need to install rspec in your base app"
+  exit
+end
+
+plugin_spec_dir = File.dirname(__FILE__)
+ActiveRecord::Base.logger = Logger.new(plugin_spec_dir + "/debug.log")
+

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification 
+name: action_throttler
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Fred Wu
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-09 00:00:00 +10:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: Action Throttler is an easy to use Rails plugin to quickly throttle application actions based on configurable duration and limit.
+email: ifredwu@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- README.md
+- Rakefile
+- action_throttler.gemspec
+- init.rb
+- install.rb
+- lib/action_throttler/actions.rb
+- lib/action_throttler/config.rb
+- lib/action_throttler/model.rb
+- lib/tasks/action_throttler.rake
+- lib/tasks/initializer/action_throttler.rb
+- lib/tasks/migration/create_action_throttler_logs.rb
+- lib/tasks/rake_helper.rb
+- spec/action_throttler_spec.rb
+- spec/spec_helper.rb
+- uninstall.rb
+has_rdoc: true
+homepage: http://github.com/fredwu/action_throttler
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Action Throttler is an easy to use Rails plugin to quickly throttle application actions based on configurable duration and limit.
+test_files: 
+- spec/action_throttler_spec.rb
+- spec/spec_helper.rb