verification 1.0.1

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in verification.gemspec
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 David Heinemeier Hansson
+
+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,34 @@
+This module provides a class-level method for specifying that certain
+actions are guarded against being called without certain prerequisites
+being met. This is essentially a special kind of before_filter.
+
+An action may be guarded against being invoked without certain request
+parameters being set, or without certain session values existing.
+
+When a verification is violated, values may be inserted into the flash, and
+a specified redirection is triggered. If no specific action is configured,
+verification failures will by default result in a 400 Bad Request response.
+
+Usage:
+
+  class GlobalController < ActionController::Base
+    # Prevent the #update_settings action from being invoked unless
+    # the 'admin_privileges' request parameter exists. The
+    # settings action will be redirected to in current controller
+    # if verification fails.
+    verify :params => "admin_privileges", :only => :update_post,
+           :redirect_to => { :action => "settings" }
+
+    # Disallow a post from being updated if there was no information
+    # submitted with the post, and if there is no active post in the
+    # session, and if there is no "note" key in the flash. The route
+    # named category_url will be redirected to if verification fails.
+
+    verify :params => "post", :session => "post", "flash" => "note",
+           :only => :update_post,
+           :add_flash => { "alert" => "Failed to create your message" },
+           :redirect_to => :category_url
+
+Note that these prerequisites are not business rules. They do not examine
+the content of the session or the parameters. That level of validation should
+be encapsulated by your domain model or helper methods in the controller.

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the verification plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+desc 'Generate documentation for the verification plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Verification'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/init.rb

@@ -0,0 +1,3 @@
+# Include hook code here
+
+require 'action_controller/verification'

data/lib/action_controller/verification.rb

@@ -0,0 +1,132 @@
+module ActionController #:nodoc:
+  module Verification #:nodoc:
+    extend ActiveSupport::Concern
+
+    include AbstractController::Callbacks, Flash, Rendering
+
+    # This module provides a class-level method for specifying that certain
+    # actions are guarded against being called without certain prerequisites
+    # being met. This is essentially a special kind of before_filter.
+    #
+    # An action may be guarded against being invoked without certain request
+    # parameters being set, or without certain session values existing.
+    #
+    # When a verification is violated, values may be inserted into the flash, and
+    # a specified redirection is triggered. If no specific action is configured,
+    # verification failures will by default result in a 400 Bad Request response.
+    #
+    # Usage:
+    #
+    #   class GlobalController < ActionController::Base
+    #     # Prevent the #update_settings action from being invoked unless
+    #     # the 'admin_privileges' request parameter exists. The
+    #     # settings action will be redirected to in current controller
+    #     # if verification fails.
+    #     verify :params => "admin_privileges", :only => :update_post,
+    #            :redirect_to => { :action => "settings" }
+    #
+    #     # Disallow a post from being updated if there was no information
+    #     # submitted with the post, and if there is no active post in the
+    #     # session, and if there is no "note" key in the flash. The route
+    #     # named category_url will be redirected to if verification fails.
+    #
+    #     verify :params => "post", :session => "post", "flash" => "note",
+    #            :only => :update_post,
+    #            :add_flash => { "alert" => "Failed to create your message" },
+    #            :redirect_to => :category_url
+    #
+    # Note that these prerequisites are not business rules. They do not examine
+    # the content of the session or the parameters. That level of validation should
+    # be encapsulated by your domain model or helper methods in the controller.
+    module ClassMethods
+      # Verify the given actions so that if certain prerequisites are not met,
+      # the user is redirected to a different action. The +options+ parameter
+      # is a hash consisting of the following key/value pairs:
+      #
+      # <tt>:params</tt>::
+      #   a single key or an array of keys that must be in the <tt>params</tt>
+      #   hash in order for the action(s) to be safely called.
+      # <tt>:session</tt>::
+      #   a single key or an array of keys that must be in the <tt>session</tt>
+      #   in order for the action(s) to be safely called.
+      # <tt>:flash</tt>::
+      #   a single key or an array of keys that must be in the flash in order
+      #   for the action(s) to be safely called.
+      # <tt>:method</tt>::
+      #   a single key or an array of keys--any one of which must match the
+      #   current request method in order for the action(s) to be safely called.
+      #   (The key should be a symbol: <tt>:get</tt> or <tt>:post</tt>, for
+      #   example.)
+      # <tt>:xhr</tt>::
+      #   true/false option to ensure that the request is coming from an Ajax
+      #   call or not.
+      # <tt>:add_flash</tt>::
+      #   a hash of name/value pairs that should be merged into the session's
+      #   flash if the prerequisites cannot be satisfied.
+      # <tt>:add_headers</tt>::
+      #   a hash of name/value pairs that should be merged into the response's
+      #   headers hash if the prerequisites cannot be satisfied.
+      # <tt>:redirect_to</tt>::
+      #   the redirection parameters to be used when redirecting if the
+      #   prerequisites cannot be satisfied. You can redirect either to named
+      #   route or to the action in some controller.
+      # <tt>:render</tt>::
+      #   the render parameters to be used when the prerequisites cannot be satisfied.
+      # <tt>:only</tt>::
+      #   only apply this verification to the actions specified in the associated
+      #   array (may also be a single value).
+      # <tt>:except</tt>::
+      #   do not apply this verification to the actions specified in the associated
+      #   array (may also be a single value).
+      def verify(options={})
+        before_filter :only => options[:only], :except => options[:except] do
+          verify_action options
+        end
+      end
+    end
+
+  private
+
+    def verify_action(options) #:nodoc:
+      if prereqs_invalid?(options)
+        flash.update(options[:add_flash])              if options[:add_flash]
+        response.headers.merge!(options[:add_headers]) if options[:add_headers]
+        apply_remaining_actions(options)               unless performed?
+      end
+    end
+
+    def prereqs_invalid?(options) # :nodoc:
+      verify_presence_of_keys_in_hash_flash_or_params(options) ||
+      verify_method(options) ||
+      verify_request_xhr_status(options)
+    end
+
+    def verify_presence_of_keys_in_hash_flash_or_params(options) # :nodoc:
+      [*options[:params] ].find { |v| v && params[v.to_sym].nil?  } ||
+      [*options[:session]].find { |v| session[v].nil? } ||
+      [*options[:flash]  ].find { |v| flash[v].nil?   }
+    end
+
+    def verify_method(options) # :nodoc:
+      [*options[:method]].all? { |v| request.request_method_symbol != v.to_sym } if options[:method]
+    end
+
+    def verify_request_xhr_status(options) # :nodoc:
+      request.xhr? != options[:xhr] unless options[:xhr].nil?
+    end
+
+    def apply_redirect_to(redirect_to_option) # :nodoc:
+      (redirect_to_option.is_a?(Symbol) && redirect_to_option != :back) ? self.__send__(redirect_to_option) : redirect_to_option
+    end
+
+    def apply_remaining_actions(options) # :nodoc:
+      case
+        when options[:render]      ; render(options[:render])
+        when options[:redirect_to] ; redirect_to(apply_redirect_to(options[:redirect_to]))
+        else head(:bad_request)
+      end
+    end
+  end
+end
+
+ActionController::Base.send :include, ActionController::Verification

data/lib/verification.rb

@@ -0,0 +1 @@
+require 'action_controller/verification'

data/test/test_helper.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'test/unit'
+require 'active_support'
+require 'action_controller'
+require File.dirname(__FILE__) + '/../lib/action_controller/verification'
+
+SharedTestRoutes = ActionDispatch::Routing::RouteSet.new
+SharedTestRoutes.draw do
+  match '/:controller(/:action(/:id))'
+end
+
+ActionController::Base.send :include, SharedTestRoutes.url_helpers
+
+module ActionController
+  class TestCase
+    setup { @routes = SharedTestRoutes }
+  end
+end

data/test/verification_test.rb

@@ -0,0 +1,288 @@
+require 'test_helper'
+
+class VerificationTestController < ActionController::Base
+  use Rack::MethodOverride
+
+  verify :only => :guarded_one, :params => "one",
+         :add_flash => { :error => 'unguarded' },
+         :redirect_to => { :action => "unguarded" }
+
+  verify :only => :guarded_two, :params => %w( one two ),
+         :redirect_to => { :action => "unguarded" }
+
+  verify :only => :guarded_with_flash, :params => "one",
+         :add_flash => { :notice => "prereqs failed" },
+         :redirect_to => { :action => "unguarded" }
+
+  verify :only => :guarded_in_session, :session => "one",
+         :redirect_to => { :action => "unguarded" }
+
+  verify :only => [:multi_one, :multi_two], :session => %w( one two ),
+         :redirect_to => { :action => "unguarded" }
+
+  verify :only => :guarded_by_method, :method => :post,
+         :redirect_to => { :action => "unguarded" }
+
+  verify :only => :guarded_by_xhr, :xhr => true,
+         :redirect_to => { :action => "unguarded" }
+
+  verify :only => :guarded_by_not_xhr, :xhr => false,
+         :redirect_to => { :action => "unguarded" }
+
+  before_filter :unconditional_redirect, :only => :two_redirects
+  verify :only => :two_redirects, :method => :post,
+         :redirect_to => { :action => "unguarded" }
+
+  verify :only => :must_be_post, :method => :post, :render => { :status => 405, :text => "Must be post" }, :add_headers => { "Allow" => "POST" }
+
+  verify :only => :must_be_put, :method => :put, :render => { :status => 405, :text => "Must be put" }, :add_headers => { "Allow" => "PUT" }
+
+  verify :only => :guarded_one_for_named_route_test, :params => "one",
+         :redirect_to => :foo_url
+
+  verify :only => :no_default_action, :params => "santa"
+
+  verify :only => :guarded_with_back, :method => :post,
+         :redirect_to => :back
+
+  def guarded_one
+    render :text => "#{params[:one]}"
+  end
+
+  def guarded_one_for_named_route_test
+    render :text => "#{params[:one]}"
+  end
+
+  def guarded_with_flash
+    render :text => "#{params[:one]}"
+  end
+
+  def guarded_two
+    render :text => "#{params[:one]}:#{params[:two]}"
+  end
+
+  def guarded_in_session
+    render :text => "#{session["one"]}"
+  end
+
+  def multi_one
+    render :text => "#{session["one"]}:#{session["two"]}"
+  end
+
+  def multi_two
+    render :text => "#{session["two"]}:#{session["one"]}"
+  end
+
+  def guarded_by_method
+    render :text => "#{request.method}"
+  end
+
+  def guarded_by_xhr
+    render :text => "#{request.xhr?}"
+  end
+
+  def guarded_by_not_xhr
+    render :text => "#{request.xhr?}"
+  end
+
+  def unguarded
+    render :text => "#{params[:one]}"
+  end
+
+  def two_redirects
+    render :nothing => true
+  end
+
+  def must_be_post
+    render :text => "Was a post!"
+  end
+
+  def must_be_put
+    render :text => "Was a put!"
+  end
+
+  def guarded_with_back
+    render :text => "#{params[:one]}"
+  end
+
+  def no_default_action
+    # Will never run
+  end
+
+  protected
+
+  def unconditional_redirect
+    redirect_to :action => "unguarded"
+  end
+end
+
+class VerificationTest < ActionController::TestCase
+  tests ::VerificationTestController
+
+  def test_using_symbol_back_with_no_referrer
+    assert_raise(ActionController::RedirectBackError) { get :guarded_with_back }
+  end
+
+  def test_using_symbol_back_redirects_to_referrer
+    @request.env["HTTP_REFERER"] = "/foo"
+    get :guarded_with_back
+    assert_redirected_to '/foo'
+  end
+
+  def test_no_deprecation_warning_for_named_route
+    assert_not_deprecated do
+      with_routing do |set|
+        set.draw do
+          match 'foo', :to => 'test#foo', :as => :foo
+          match 'verification_test/:action', :to => ::VerificationTestController
+        end
+        get :guarded_one_for_named_route_test, :two => "not one"
+        assert_redirected_to '/foo'
+      end
+    end
+  end
+
+  def test_guarded_one_with_prereqs
+    get :guarded_one, :one => "here"
+    assert_equal "here", @response.body
+  end
+
+  def test_guarded_one_without_prereqs
+    get :guarded_one
+    assert_redirected_to :action => "unguarded"
+    assert_equal 'unguarded', flash[:error]
+  end
+
+  def test_guarded_with_flash_with_prereqs
+    get :guarded_with_flash, :one => "here"
+    assert_equal "here", @response.body
+    assert flash.empty?
+  end
+
+  def test_guarded_with_flash_without_prereqs
+    get :guarded_with_flash
+    assert_redirected_to :action => "unguarded"
+    assert_equal "prereqs failed", flash[:notice]
+  end
+
+  def test_guarded_two_with_prereqs
+    get :guarded_two, :one => "here", :two => "there"
+    assert_equal "here:there", @response.body
+  end
+
+  def test_guarded_two_without_prereqs_one
+    get :guarded_two, :two => "there"
+    assert_redirected_to :action => "unguarded"
+  end
+
+  def test_guarded_two_without_prereqs_two
+    get :guarded_two, :one => "here"
+    assert_redirected_to :action => "unguarded"
+  end
+
+  def test_guarded_two_without_prereqs_both
+    get :guarded_two
+    assert_redirected_to :action => "unguarded"
+  end
+
+  def test_unguarded_with_params
+    get :unguarded, :one => "here"
+    assert_equal "here", @response.body
+  end
+
+  def test_unguarded_without_params
+    get :unguarded
+    assert @response.body.blank?
+  end
+
+  def test_guarded_in_session_with_prereqs
+    get :guarded_in_session, {}, "one" => "here"
+    assert_equal "here", @response.body
+  end
+
+  def test_guarded_in_session_without_prereqs
+    get :guarded_in_session
+    assert_redirected_to :action => "unguarded"
+  end
+
+  def test_multi_one_with_prereqs
+    get :multi_one, {}, "one" => "here", "two" => "there"
+    assert_equal "here:there", @response.body
+  end
+
+  def test_multi_one_without_prereqs
+    get :multi_one
+    assert_redirected_to :action => "unguarded"
+  end
+
+  def test_multi_two_with_prereqs
+    get :multi_two, {}, "one" => "here", "two" => "there"
+    assert_equal "there:here", @response.body
+  end
+
+  def test_multi_two_without_prereqs
+    get :multi_two
+    assert_redirected_to :action => "unguarded"
+  end
+
+  def test_guarded_by_method_with_prereqs
+    post :guarded_by_method
+    assert_equal "POST", @response.body
+  end
+
+  def test_guarded_by_method_without_prereqs
+    get :guarded_by_method
+    assert_redirected_to :action => "unguarded"
+  end
+
+  def test_guarded_by_xhr_with_prereqs
+    xhr :post, :guarded_by_xhr
+    assert_equal "true", @response.body
+  end
+
+  def test_guarded_by_xhr_without_prereqs
+    get :guarded_by_xhr
+    assert_redirected_to :action => "unguarded"
+  end
+
+  def test_guarded_by_not_xhr_with_prereqs
+    get :guarded_by_not_xhr
+    assert_equal "false", @response.body
+  end
+
+  def test_guarded_by_not_xhr_without_prereqs
+    xhr :post, :guarded_by_not_xhr
+    assert_redirected_to :action => "unguarded"
+  end
+
+  def test_guarded_post_and_calls_render_succeeds
+    post :must_be_post
+    assert_equal "Was a post!", @response.body
+  end
+
+  def test_guarded_put_and_calls_render_succeeds
+    put :must_be_put
+    assert_equal "Was a put!", @response.body
+  end
+
+  def test_guarded_post_with_put_params_and_calls_render_succeeds
+    post :must_be_put, '_method' => 'put'
+    assert_equal "Was a put!", @response.body
+  end
+
+  def test_default_failure_should_be_a_bad_request
+    post :no_default_action
+    assert_response :bad_request
+  end
+
+  def test_guarded_post_and_calls_render_fails_and_sets_allow_header
+    get :must_be_post
+    assert_response 405
+    assert_equal "Must be post", @response.body
+    assert_equal "POST", @response.headers["Allow"]
+  end
+
+  def test_second_redirect
+    assert_nothing_raised { get :two_redirects }
+  end
+end

data/verification.gemspec

@@ -0,0 +1,20 @@
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "verification"
+  s.version     = "1.0.1"
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["David Heinemeier Hansson"]
+  s.email       = ["david@loudthinking.com"]
+  s.homepage    = "https://rubygems.org/gems/verification"
+  s.summary     = %q{Verify preconditions for Rails actions}
+  s.description = %q{Verify preconditions for Rails actions}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency('activesupport', '~>3.0.0')
+  s.add_dependency('actionpack', '~>3.0.0')
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification 
+name: verification
+version: !ruby/object:Gem::Version 
+  hash: 21
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 1
+  version: 1.0.1
+platform: ruby
+authors: 
+- David Heinemeier Hansson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-16 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: actionpack
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id002
+description: Verify preconditions for Rails actions
+email: 
+- david@loudthinking.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- MIT-LICENSE
+- README
+- Rakefile
+- init.rb
+- lib/action_controller/verification.rb
+- lib/verification.rb
+- test/test_helper.rb
+- test/verification_test.rb
+- verification.gemspec
+has_rdoc: true
+homepage: https://rubygems.org/gems/verification
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: Verify preconditions for Rails actions
+test_files: 
+- test/test_helper.rb
+- test/verification_test.rb