action_interceptor 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 31e855e9e9869ca8e5d409a7016be38bd81f560a
-  data.tar.gz: 5ee08d985554e577b922afd1b5d53db794782794
+  metadata.gz: 329436e7ee0f1ad6c5ce0f1891cfe6c8ae7dbe76
+  data.tar.gz: 6f0b1b10adf2484ec53cb35245bcc02bf5d3e6d6
 SHA512:
-  metadata.gz: 08c253742ec490768f8cac0f082f2692a8b025153a2768c8a2832c64874be5755c1a45ad0542ebc6f7cf226278665131e487d2c714ca3d5043e47bc442c099f2
-  data.tar.gz: fe5c9c8635292d2db08b17837f82743d6d14eb645707c702fb26119daf1424a22afaa2e10377f1350f07ac416922ae04465aaf8e82206dd7195a8035708b6029
+  metadata.gz: 1cbcf3eae9d54f8b3fd53e8b72708312af35a89336951246f933ecda523ef265525ce655825cecd83a150ed173fe6007936a29d5db834ca9ada91157afede299
+  data.tar.gz: d7bfd96282fe7e6b6b79b723250b694e7fca4f45bb623079824b53d582323dbc339dc4dbc15b68a72656356a6a357ff4c04220098b1915a13a3341668d335f41

data/README.md

@@ -4,7 +4,7 @@
 
 Action Interceptor is a Rails engine that makes it easy to have controllers intercept
 actions from other controllers, have users perform a task and then return them to where
-they were before.
+they were when the interception happened.
 
 This can be used, for example, for registration, authentication, signing terms of use, etc.
 
@@ -22,43 +22,132 @@ And then execute:
 $ bundle install
 ```
 
+Finally, run the following rake task to add
+Action Interceptor's initializer to your application:
+
+```sh
+$ rake action_interceptor:install
+```
+
 ## Usage
-    
-Add the following line to controllers that should
-intercept actions from other controllers:
+
+Interceptors are blocks of code that are declared in Action Interceptor's
+initializer. They execute in the context of your controllers and work
+very much like before_filters.
+
+For example, the following interceptor could be used to ensure that users
+have filled out a registration form:
 
 ```rb
-interceptor
+interceptor :registration do
+
+  return if current_user.try(:is_registered?)
+
+  respond_to do |format|
+    format.html { redirect_to register_path }
+    format.json { head(:forbidden) }
+  end
+
+end
 ```
-    
-Then declare the controllers and actions to be intercepted:
+
+What makes interceptors different from before_filters is that they will
+save the user's current url before redirecting. This is done through
+signed url params by default, falling back to session variables if those
+params are absent or invalid.
+
+Once declared, you can use an interceptor in any controller. For example,
+you might want to ensure that all logged in users have to complete
+a form before using your site. In that case, you could add the following
+to your `ApplicationController`:
 
 ```rb
-intercept ApplicationController, only: :index do
-  # Block that returns:
-  # The redirection path if the action is to be intercepted
-  # Nil/false otherwise
+class ApplicationController < ActionController::Base
+
+  interceptor :registration
+
 end
 ```
 
-When users complete the task, use the following method to
-redirect them back to where they were before:
+The controllers your interceptors redirect to should
+call the `acts_as_interceptor` method:
+
+```rb
+class RegistrationsController < ApplicationController
+
+  acts_as_interceptor
+
+  skip_interceptor :registration, only: [:new, :create]
+
+end
+```
+
+As shown above, interceptions work like before_filters and
+can be skipped using the skip_interceptor method.
+
+The `acts_as_interceptor` method will ensure the following:
+
+- The `url_options` method for that controller will be overriden, causing all
+  links and redirects for the controller and associated views to include
+  the signed return url. This can be skipped by calling `acts_as_interceptor`
+  like this: `acts_as_interceptor override_url_options: false`. In that case,
+  you are responsible for passing the `intercepted_url_hash` to any internal
+  links and redirects.
+
+- The following convenience methods will be added to the controller:
+  `redirect_back(options = {})`, `intercepted_url`, `intercepted_url=`,
+  `intercepted_url_hash`, `without_interceptor(&block)`,
+  `url_options_without_interceptor` and `url_options_with_interceptor`.
+  These methods have the following behavior:
+
+  - redirect_back(options = {}) redirects the user back to where the
+    interception occurred, passing the given options to the redirect method.
+
+  - `intercepted_url` returns the intercepted url. Can be used in views to make
+    links that redirect the user back to where the interception happened.
+
+  - `intercepted_url=` can be used to overwrite the intercepted url, if needed.
+
+  - `intercepted_url_hash` returns a hash containing the `interceptor_url_key`
+    and the signed `intercepted_url`.
+
+  - `without_interceptor(&block)` executes a block with the old url options.
+
+  - `url_options_without_interceptor` returns the old url options.
+
+  - `url_options_with_interceptor` returns the old url options merged with
+    the `intercepted_url_hash`. Can be used even if you specified
+    `override_url_options: false`.
+
+When users complete the given task, use the following method to
+redirect them back to where the interception occurred:
 
 ```rb
 redirect_back
 ```
 
-Alternatively, you can use `redirect_url` in views:
+Alternatively, you can use `intercepted_url` in views:
 
 ```erb
-<%= link_to 'Back', redirect_url %>
+<%= link_to 'Back', intercepted_url %>
 ```
 
+Finally, just by including the gem in your app, the following convenience
+methods will be added to all controllers: `current_url`, `current_url_hash`,
+`current_page?(url)` and `with_interceptor(&block)`.
+
+- `current_url` returns the current url.
+- `current_url_hash` returns a hash containing the `intercepted_url_key` and the
+  `current_url`, signed and encrypted.
+- `current_page?(url)` returns true iif the given url is the `current_url`.
+- `with_interceptor(&block)` executes the given block as if it was an
+  interceptor for the current controller.
+
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Write tests for your feature
+3. Write specs for your feature
 4. Implement your new feature
 5. Test your feature (`rake`)
 6. Commit your changes (`git commit -am 'Added some feature'`)
@@ -87,7 +176,8 @@ Alternatively, you can use `redirect_url` in views:
 
 ## Testing
 
-To run all existing tests for action_interceptor, simply execute the following from the main folder:
+To run all existing tests for Action Interceptor,
+simply execute the following from the main folder:
 
 ```sh
 $ rake

data/Rakefile

@@ -12,7 +12,7 @@ Bundler::GemHelper.install_tasks
 
 require 'rake/testtask'
 
-Rake::TestTask.new(:spec => 'app:db:test:prepare') do |t|
+Rake::TestTask.new(:spec) do |t|
   t.libs << 'lib'
   t.libs << 'spec'
   t.pattern = 'spec/**/*_spec.rb'

data/lib/action_interceptor.rb

@@ -1,11 +1,14 @@
 require 'action_interceptor/engine'
 
 module ActionInterceptor
-  mattr_reader :intercepted_url_key
-
   def self.intercepted_url_key(key = nil)
-    return @intercepted_url_key || :r unless key
-    @intercepted_url_key = key
+    @intercepted_url_key = key unless key.blank?
+    @intercepted_url_key || :r
+  end
+
+  def self.override_url_options(bool = nil)
+    @override_url_options = bool unless bool.nil?
+    @override_url_options.nil? ? true : @override_url_options
   end
 
   def self.interceptors

data/lib/action_interceptor/controller.rb

@@ -11,8 +11,6 @@ module ActionInterceptor
       base.extend(ClassMethods)
     end
 
-    protected
-
     def current_url
       "#{request.protocol}#{request.host_with_port}#{request.fullpath}"
     end
@@ -22,7 +20,7 @@ module ActionInterceptor
       url.blank? || URI(url).path == request.path
     end
 
-    def encrypted_url_hash
+    def current_url_hash
       return @current_url_hash if @current_url_hash
 
       key = ActionInterceptor.intercepted_url_key
@@ -33,14 +31,15 @@ module ActionInterceptor
       @current_url_hash = {key => url}
     end
 
-    def interception_exec(&block)
-      @original_default_url_options ||= default_url_options
+    # Executes the given block as if it was an interceptor
+    def with_interceptor(&block)
+      @previous_default_url_options ||= default_url_options
 
       begin
         # Send the referer with intercepted requests
         # So we don't rely on the user's browser to do it for us
-        self.default_url_options = @original_default_url_options
-                                     .merge(encrypted_url_hash)
+        self.default_url_options = @previous_default_url_options
+                                     .merge(current_url_hash)
 
         # Execute the block as if it was defined in this controller
         instance_exec &block
@@ -49,13 +48,13 @@ module ActionInterceptor
         # and return the given value
         e.exit_value
       ensure
-        self.default_url_options = @original_default_url_options
+        self.default_url_options = @previous_default_url_options
       end
     end
 
     module ClassMethods
 
-      def interception(*interceptor_names, &block)
+      def interceptor(*interceptor_names, &block)
         options = interceptor_names.extract_options!
         filter_name = options.delete(:filter_name)
         fnames = interceptor_names.collect do |iname|
@@ -66,7 +65,7 @@ module ActionInterceptor
             blk = block || ActionInterceptor.interceptors[iname]
             raise UndefinedInterceptor, iname unless blk
 
-            interception_exec &blk
+            with_interceptor &blk
           end
 
           fname
@@ -75,7 +74,7 @@ module ActionInterceptor
         before_filter *fnames, options
       end
 
-      def skip_interception(*interceptor_names)
+      def skip_interceptor(*interceptor_names)
         options = interceptor_names.extract_options!
         filter_name = options.delete(:filter_name)
         fnames = interceptor_names.collect do |iname|
@@ -85,36 +84,19 @@ module ActionInterceptor
         skip_before_filter *fnames, options
       end
 
-      def acts_as_interceptor
+      def acts_as_interceptor(options = {})
         return if is_interceptor
         self.is_interceptor = true
 
-        class_eval do
-
-          helper_method :intercepted_url
-
-          alias_method :url_options_without_interceptor, :url_options
-
-          def url_options
-            return @interceptor_url_options if @interceptor_url_options
-
-            url = Encryptor.encrypt_and_sign(intercepted_url)
-            key = ActionInterceptor.intercepted_url_key
-            @interceptor_url_options = {key => url}.merge(super)
-          end
+        @override_url_options = options[:override_url_options].nil? ? \
+                                  ActionInterceptor.override_url_options : \
+                                  options[:override_url_options]
 
-          def without_interceptor_url_options(&block)
-            url_options_with_interceptor = url_options
+        class_eval do
 
-            begin
-              @interceptor_url_options = url_options_without_interceptor
-              yield block
-            ensure
-              @interceptor_url_options = url_options_with_interceptor
-            end
-          end
+          attr_writer :intercepted_url
 
-          alias_method :without_interceptor, :without_interceptor_url_options
+          helper_method :intercepted_url
 
           def intercepted_url
             return @intercepted_url if @intercepted_url
@@ -123,7 +105,7 @@ module ActionInterceptor
             begin
               # URL params are the most reliable, as they preserve
               # state even if the user presses the back button
-              # Prevent Open Redirect vulnerability
+              # We need to sign them to prevent the Open Redirect vulnerability
               @intercepted_url = Encryptor.decrypt_and_verify(params[key])
             rescue ActiveSupport::MessageVerifier::InvalidSignature
               # If the param is not available, use our best guess
@@ -137,11 +119,43 @@ module ActionInterceptor
             @intercepted_url
           end
 
+          def intercepted_url_hash
+            return @intercepted_url_hash if @intercepted_url_hash
+            url = Encryptor.encrypt_and_sign(intercepted_url)
+            key = ActionInterceptor.intercepted_url_key
+
+            @intercepted_url_hash = {key => url}
+          end
+
+          alias_method :url_options_without_interceptor, :url_options
+
+          def url_options_with_interceptor
+            return @url_options_with_interceptor \
+              if @url_options_with_interceptor
+
+            @url_options_with_interceptor = intercepted_url_hash.merge(
+                                              url_options_without_interceptor)
+          end
+
+          alias_method :url_options, :url_options_with_interceptor \
+            if @override_url_options.nil? || @override_url_options
+
+          def without_interceptor(&block)
+            previous_url_options = url_options_with_interceptor
+
+            begin
+              @url_options_with_interceptor = url_options_without_interceptor
+              yield block
+            ensure
+              @url_options_with_interceptor = previous_url_options
+            end
+          end
+
           def redirect_back(options = {})
             url = intercepted_url
 
             # Disable the return_to param
-            without_interceptor_url_options do
+            without_interceptor do
               # Convert '/' back to root_url
               # Also, prevent self redirects
               url = root_url if url == '/' || current_page?(url)

data/lib/action_interceptor/version.rb

@@ -1,4 +1,4 @@
 module ActionInterceptor
-  VERSION = '0.0.3'
+  VERSION = '0.1.0'
 end
 

data/spec/dummy/app/controllers/application_controller.rb

@@ -1,3 +1,7 @@
 class ApplicationController < ActionController::Base
   protect_from_forgery
+
+  cattr_accessor :is_registered
+
+  interceptor :registration, :my_interceptor
 end

data/spec/dummy/app/controllers/home_controller.rb

@@ -0,0 +1,10 @@
+class HomeController < ActionController::Base
+  skip_interceptor :registration, only: :index
+  
+  def index
+  end
+  
+  def api
+  end
+end
+

data/spec/dummy/app/controllers/registrations_controller.rb

@@ -0,0 +1,14 @@
+class RegistrationsController < ActionController::Base
+  acts_as_interceptor
+
+  skip_interceptor :registration
+
+  def new
+    redirect_to registration_register_path
+  end
+
+  def register
+    redirect_back notice: 'Registration successful!'
+  end
+end
+

data/spec/dummy/config/application.rb

@@ -22,4 +22,3 @@ module Dummy
     config.i18n.enforce_available_locales = true
   end
 end
-

data/spec/dummy/config/initializers/action_interceptor.rb

@@ -0,0 +1,11 @@
+ActionInterceptor.configure do
+  intercepted_url_key :dummy_key
+
+  override_url_options true
+
+  interceptor :registration do
+  end
+
+  interceptor :my_interceptor do
+  end
+end

data/spec/dummy/config/routes.rb

@@ -1,2 +1,9 @@
 Rails.application.routes.draw do
+  resource :registration, :only => [:new] do
+    get :register
+  end
+
+  get 'home/api'
+
+  root to: 'home#index'
 end

data/spec/lib/action_interceptor/controller_spec.rb

@@ -0,0 +1,57 @@
+require 'spec_helper'
+
+module ActionInterceptor
+  describe Controller do
+
+    it 'modifies ActionController::Base' do
+      expect(ActionController::Base).to respond_to(:is_interceptor)
+      expect(ActionController::Base).to respond_to(:interceptor_filters)
+      expect(ActionController::Base.is_interceptor).to be_false
+      expect(ActionController::Base.interceptor_filters).to be_a(Hash)
+
+      expect(ActionController::Base).to respond_to(:interceptor)
+      expect(ActionController::Base).to respond_to(:skip_interceptor)
+      expect(ActionController::Base).to respond_to(:acts_as_interceptor)
+
+      expect(ActionController::Base.new).to respond_to(:current_page?)
+      expect(ActionController::Base.new).to respond_to(:current_url)
+      expect(ActionController::Base.new).to respond_to(:current_url_hash)
+      expect(ActionController::Base.new).to respond_to(:with_interceptor)
+    end
+
+    it 'modifies classes that act_as_interceptor' do
+      expect(RegistrationsController.is_interceptor).to be_true
+
+      expect(RegistrationsController.new).to respond_to(:intercepted_url)
+      expect(RegistrationsController.new).to respond_to(:intercepted_url=)
+      expect(RegistrationsController.new).to respond_to(:intercepted_url_hash)
+      expect(RegistrationsController.new).to(
+        respond_to(:url_options_without_interceptor))
+      expect(RegistrationsController.new).to(
+        respond_to(:url_options_with_interceptor))
+      expect(RegistrationsController.new).to respond_to(:without_interceptor)
+      expect(RegistrationsController.new).to respond_to(:redirect_back)
+    end
+
+    it 'registers and skips before_filters' do
+      filters = RegistrationsController.new._process_action_callbacks
+                                           .collect{|c| c.filter}
+      expect(filters).not_to include(:my_interceptor)
+
+      RegistrationsController.interceptor :my_interceptor
+      filters = RegistrationsController.new._process_action_callbacks
+                                           .collect{|c| c.filter}
+      expect(filters).to include(:my_interceptor)
+
+      filters = ApplicationController.new._process_action_callbacks
+                                         .collect{|c| c.filter}
+      expect(filters).to include(:my_interceptor)
+
+      ApplicationController.skip_interceptor :my_interceptor
+      filters = ApplicationController.new._process_action_callbacks
+                                         .collect{|c| c.filter}
+      expect(filters).not_to include(:my_interceptor)
+    end
+
+  end
+end

data/spec/lib/action_interceptor/encryptor_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+module ActionInterceptor
+  describe Encryptor do
+
+    it 'encrypts and decrypts strings' do
+      my_string = 'My string'
+      encrypted_string = Encryptor.encrypt_and_sign(my_string)
+      expect(encrypted_string).not_to include(my_string)
+
+      decrypted_string = Encryptor.decrypt_and_verify(encrypted_string)
+      expect(decrypted_string).to eq(my_string)
+
+      expect{Encryptor.decrypt_and_verify(my_string)}.to(
+        raise_error(ActiveSupport::MessageVerifier::InvalidSignature))
+    end
+
+  end
+end

data/spec/lib/action_interceptor_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe ActionInterceptor do
+  it 'must be configurable' do
+    expect(ActionInterceptor.intercepted_url_key).to eq(:dummy_key)
+    expect(ActionInterceptor.override_url_options).to be_true
+    expect(ActionInterceptor.interceptors.keys).to include(:registration)
+
+    my_block = lambda { 'my_block' }
+
+    ActionInterceptor.configure do
+      intercepted_url_key :my_key
+      override_url_options false
+      interceptor :my_name, &my_block
+    end
+
+    expect(ActionInterceptor.intercepted_url_key).to eq(:my_key)
+    expect(ActionInterceptor.override_url_options).to be_false
+    expect(ActionInterceptor.interceptors).to include({:my_name => my_block})
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: action_interceptor
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Dante Soares
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-16 00:00:00.000000000 Z
+date: 2014-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,20 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.1'
-- !ruby/object:Gem::Dependency
-  name: public_suffix
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.9.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.9.1
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -66,8 +52,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Facilitates redirection to and from controllers that require users to
-  perform some task, then redirect them back to where they were.
+description: Action Interceptor provides controllers that require users to perform
+  some task, then redirect them back to the page they were on. Useful for authentication,
+  registration, signing terms of use, etc.
 email:
 - dms3@rice.edu
 executables: []
@@ -89,8 +76,9 @@ files:
 - spec/dummy/app/assets/javascripts/application.js
 - spec/dummy/app/assets/stylesheets/application.css
 - spec/dummy/app/controllers/application_controller.rb
+- spec/dummy/app/controllers/home_controller.rb
+- spec/dummy/app/controllers/registrations_controller.rb
 - spec/dummy/app/helpers/application_helper.rb
-- spec/dummy/app/views/layouts/application.html.erb
 - spec/dummy/bin/bundle
 - spec/dummy/bin/rails
 - spec/dummy/bin/rake
@@ -102,6 +90,7 @@ files:
 - spec/dummy/config/environments/development.rb
 - spec/dummy/config/environments/production.rb
 - spec/dummy/config/environments/test.rb
+- spec/dummy/config/initializers/action_interceptor.rb
 - spec/dummy/config/initializers/backtrace_silencers.rb
 - spec/dummy/config/initializers/filter_parameter_logging.rb
 - spec/dummy/config/initializers/inflections.rb
@@ -111,13 +100,16 @@ files:
 - spec/dummy/config/initializers/wrap_parameters.rb
 - spec/dummy/config/locales/en.yml
 - spec/dummy/config/routes.rb
-- spec/dummy/db/development.sqlite3
 - spec/dummy/db/test.sqlite3
 - spec/dummy/log/development.log
+- spec/dummy/log/test.log
 - spec/dummy/public/404.html
 - spec/dummy/public/422.html
 - spec/dummy/public/500.html
 - spec/dummy/public/favicon.ico
+- spec/lib/action_interceptor/controller_spec.rb
+- spec/lib/action_interceptor/encryptor_spec.rb
+- spec/lib/action_interceptor_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/openstax/action_interceptor
 licenses:
@@ -147,8 +139,9 @@ test_files:
 - spec/dummy/app/assets/javascripts/application.js
 - spec/dummy/app/assets/stylesheets/application.css
 - spec/dummy/app/controllers/application_controller.rb
+- spec/dummy/app/controllers/home_controller.rb
+- spec/dummy/app/controllers/registrations_controller.rb
 - spec/dummy/app/helpers/application_helper.rb
-- spec/dummy/app/views/layouts/application.html.erb
 - spec/dummy/bin/bundle
 - spec/dummy/bin/rails
 - spec/dummy/bin/rake
@@ -159,6 +152,7 @@ test_files:
 - spec/dummy/config/environments/development.rb
 - spec/dummy/config/environments/production.rb
 - spec/dummy/config/environments/test.rb
+- spec/dummy/config/initializers/action_interceptor.rb
 - spec/dummy/config/initializers/backtrace_silencers.rb
 - spec/dummy/config/initializers/filter_parameter_logging.rb
 - spec/dummy/config/initializers/inflections.rb
@@ -169,13 +163,16 @@ test_files:
 - spec/dummy/config/locales/en.yml
 - spec/dummy/config/routes.rb
 - spec/dummy/config.ru
-- spec/dummy/db/development.sqlite3
 - spec/dummy/db/test.sqlite3
 - spec/dummy/log/development.log
+- spec/dummy/log/test.log
 - spec/dummy/public/404.html
 - spec/dummy/public/422.html
 - spec/dummy/public/500.html
 - spec/dummy/public/favicon.ico
 - spec/dummy/Rakefile
 - spec/dummy/README.md
+- spec/lib/action_interceptor/controller_spec.rb
+- spec/lib/action_interceptor/encryptor_spec.rb
+- spec/lib/action_interceptor_spec.rb
 - spec/spec_helper.rb

data/spec/dummy/app/views/layouts/application.html.erb

@@ -1,14 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-  <title>Dummy</title>
-  <%= stylesheet_link_tag    "application", media: "all", "data-turbolinks-track" => true %>
-  <%= javascript_include_tag "application", "data-turbolinks-track" => true %>
-  <%= csrf_meta_tags %>
-</head>
-<body>
-
-<%= yield %>
-
-</body>
-</html>