cancan 1.2.0 → 1.3.2

data/CHANGELOG.rdoc

@@ -1,3 +1,41 @@
+1.3.2 (August 7, 2010)
+
+* Fixing slice error when passing in custom resource name - see issue #112
+
+
+1.3.1 (August 6, 2010)
+
+* Fixing protected sanitize_sql error - see issue #111
+
+
+1.3.0 (August 6, 2010)
+
+* Adding :find_by option to load_resource - see issue #19
+
+* Adding :singleton option to load_resource - see issue #93
+
+* Supporting multiple resources in :through option for polymorphic
+associations - see issue #73
+
+* Supporting Single Table Inheritance for "can" comparisons - see issue #55
+
+* Adding :instance_name option to load/authorize_resource - see issue #44
+
+* Don't pass nil to "new" to keep MongoMapper happy - see issue #63
+
+* Parent resources are now authorized with :read action.
+
+* Changing :resource option in load/authorize_resource back to :class with ability to pass false
+
+* Removing :nested option in favor of :through option with separate load/authorize call
+
+* Moving internal logic from ResourceAuthorization to ControllerResource class
+
+* Supporting multiple "can" and "cannot" calls with accessible_by (thanks funny-falcon) - see issue #71
+
+* Supporting deeply nested aliases - see issue #98
+
+
 1.2.0 (July 16, 2010)
 
 * Load nested parent resources on collection actions such as "index" (thanks dohzya)

data/README.rdoc

@@ -1,18 +1,22 @@
 = CanCan
 
-Wiki[http://wiki.github.com/ryanb/cancan] | RDocs[http://rdoc.info/projects/ryanb/cancan] | Screencast[http://railscasts.com/episodes/192-authorization-with-cancan] | Metrics[http://getcaliper.com/caliper/project?repo=git%3A%2F%2Fgithub.com%2Fryanb%2Fcancan.git]
+Wiki[http://wiki.github.com/ryanb/cancan] | RDocs[http://rdoc.info/projects/ryanb/cancan] | Screencast[http://railscasts.com/episodes/192-authorization-with-cancan]
 
-CanCan is an authorization solution for Ruby on Rails. This restricts what a given user is allowed to access throughout the application. It is completely decoupled from any role based implementation and focusses on keeping permission logic in a single location (the +Ability+ class) so it is not duplicated across controllers, views, and database queries.
+CanCan is an authorization solution for Ruby on Rails for restricting what a given user is allowed to access throughout the application. It does not care how your user roles are defined, it simply focusses on keeping permission logic in a single location (the +Ability+ class) so it is not duplicated across controllers, views, and database queries.
 
-This assumes you already have authentication (such as Authlogic[http://github.com/binarylogic/authlogic] or Devise[http://github.com/plataformatec/devise]) that provides a +current_user+ method which CanCan relies on. See {Changing Defaults}[http://wiki.github.com/ryanb/cancan/changing-defaults] if you need different behavior.
+By default, the +current_user+ method is required, so if you have not already, set up some authentication (such as Authlogic[http://github.com/binarylogic/authlogic] or Devise[http://github.com/plataformatec/devise]). See {Changing Defaults}[http://wiki.github.com/ryanb/cancan/changing-defaults] if you need different behavior.
 
 
 == Installation
 
-CanCan is provided as a gem. Simply include it in your environment.rb or Gemfile.
+To install CanCan, include the gem in the environment.rb in Rails 2.3.
 
   config.gem "cancan"
 
+Or the Gemfile in Rails 3.
+
+  gem "cancan"
+
 Alternatively it can be installed as a plugin.
 
   script/plugin install git://github.com/ryanb/cancan.git
@@ -20,11 +24,11 @@ Alternatively it can be installed as a plugin.
 
 == Getting Started
 
-First, define a class called +Ability+ in "models/ability.rb". It should look something like this.
+First, define a class called +Ability+ in "models/ability.rb" or anywhere else in the load path. It should look something like this.
 
   class Ability
     include CanCan::Ability
-  
+
     def initialize(user)
       if user.admin?
         can :manage, :all
@@ -55,7 +59,7 @@ Setting this for every action can be tedious, therefore the +load_and_authorize_
 
   class ArticlesController < ApplicationController
     load_and_authorize_resource
-    
+
     def show
       # @article is already loaded and authorized
     end
@@ -136,7 +140,8 @@ See {Fetching Records}[http://wiki.github.com/ryanb/cancan/fetching-records] for
 
 == Additional Docs
 
-* {Upgrading to 1.1}[http://wiki.github.com/ryanb/cancan/upgrading-to-11]
+* {Upgrading to 1.3}[http://wiki.github.com/ryanb/cancan/upgrading-to-13]
+* {Nested Resources}[http://wiki.github.com/ryanb/cancan/nested-resources]
 * {Testing Abilities}[http://wiki.github.com/ryanb/cancan/testing-abilities]
 * {Accessing Request Data}[http://wiki.github.com/ryanb/cancan/accessing-request-data]
 * {Admin Namespace}[http://wiki.github.com/ryanb/cancan/admin-namespace]
@@ -144,4 +149,4 @@ See {Fetching Records}[http://wiki.github.com/ryanb/cancan/fetching-records] for
 
 == Special Thanks
 
-CanCan was inspired by declarative_authorization[http://github.com/stffn/declarative_authorization/] and aegis[http://github.com/makandra/aegis]. Many thanks to the authors and contributors.
+CanCan was inspired by declarative_authorization[http://github.com/stffn/declarative_authorization/] and aegis[http://github.com/makandra/aegis]. Also many thanks to the CanCan contributors[http://github.com/ryanb/cancan/contributors]. See the CHANGELOG[http://github.com/ryanb/cancan/blob/master/CHANGELOG.rdoc] for the full list.

data/Rakefile

@@ -1,13 +1,13 @@
-require 'rubygems'
-require 'rake'
-require 'spec/rake/spectask'
-
-spec_files = Rake::FileList["spec/**/*_spec.rb"]
-
-desc "Run specs"
-Spec::Rake::SpecTask.new do |t|
-  t.spec_files = spec_files
-  t.spec_opts = ["-c"]
-end
-
+require 'rubygems'
+require 'rake'
+require 'spec/rake/spectask'
+
+spec_files = Rake::FileList["spec/**/*_spec.rb"]
+
+desc "Run specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = spec_files
+  t.spec_opts = ["-c"]
+end
+
 task :default => :spec

data/lib/cancan.rb

@@ -1,7 +1,7 @@
 require 'cancan/ability'
 require 'cancan/can_definition'
 require 'cancan/controller_resource'
-require 'cancan/resource_authorization'
 require 'cancan/controller_additions'
 require 'cancan/active_record_additions'
 require 'cancan/exceptions'
+require 'cancan/query'

data/lib/cancan/ability.rb

@@ -50,8 +50,10 @@ module CanCan
     # Also see the RSpec Matchers to aid in testing.
     def can?(action, subject, *extra_args)
       raise Error, "Nom nom nom. I eated it." if action == :has && subject == :cheezburger
-      can_definition = matching_can_definition(action, subject)
-      can_definition && can_definition.can?(action, subject, extra_args)
+      match = relevant_can_definitions(action, subject).detect do |can_definition|
+        can_definition.matches_conditions?(action, subject, extra_args)
+      end
+      match ? match.base_behavior : false
     end
 
     # Convenience method which works the same as "can?" but returns the opposite value.
@@ -180,47 +182,42 @@ module CanCan
       @aliased_actions = {}
     end
 
-    # Returns a hash of conditions which match the given ability. This is useful if you need to generate a database
-    # query based on the current ability.
-    #
-    #   can :read, Article, :visible => true
-    #   conditions :read, Article # returns { :visible => true }
-    #
-    # Normally you will not call this method directly, but instead go through ActiveRecordAdditions#accessible_by method.
-    #
-    # If the ability is not defined then false is returned so be sure to take that into consideration.
-    # If the ability is defined using a block then this will raise an exception since a hash of conditions cannot be
-    # determined from that.
-    def conditions(action, subject, options = {})
-      can_definition = matching_can_definition(action, subject)
-      if can_definition
-        raise Error, "Cannot determine ability conditions from block for #{action.inspect} #{subject.inspect}" if can_definition.block
-        can_definition.conditions(options) || {}
-      else
-        false
-      end
-    end
-
-    # Returns the associations used in conditions. This is usually used in the :joins option for a search.
-    # See ActiveRecordAdditions#accessible_by for use in Active Record.
-    def association_joins(action, subject)
-      can_definition = matching_can_definition(action, subject)
-      if can_definition
-        raise Error, "Cannot determine association joins from block for #{action.inspect} #{subject.inspect}" if can_definition.block
-        can_definition.association_joins
-      end
+    # Returns a CanCan::Query instance to help generate database queries based on the ability.
+    # If any relevant can definitions use a block then an exception will be raised because an
+    # SQL query cannot be generated from blocks of code.
+    def query(action, subject)
+      Query.new(subject, relevant_can_definitions_for_query(action, subject))
     end
 
     private
 
+    # Accepts a hash of aliased actions and returns an array of actions which match.
+    # This should be called before "matches?" and other checking methods since they
+    # rely on the actions to be expanded.
+    def expand_actions(actions)
+      actions.map do |action|
+        aliased_actions[action] ? [action, *expand_actions(aliased_actions[action])] : action
+      end.flatten
+    end
+
     def can_definitions
       @can_definitions ||= []
     end
 
-    def matching_can_definition(action, subject)
-      can_definitions.reverse.detect do |can_definition|
-        can_definition.expand_actions(aliased_actions)
-        can_definition.matches? action, subject
+    # Returns an array of CanDefinition instances which match the action and subject
+    # This does not take into consideration any hash conditions or block statements
+    def relevant_can_definitions(action, subject)
+      can_definitions.reverse.select do |can_definition|
+        can_definition.expanded_actions = expand_actions(can_definition.actions)
+        can_definition.relevant? action, subject
+      end
+    end
+
+    def relevant_can_definitions_for_query(action, subject)
+      relevant_can_definitions(action, subject).each do |can_definition|
+        if can_definition.only_block?
+          raise Error, "Cannot determine SQL conditions or joins from block for #{action.inspect} #{subject.inspect}"
+        end
       end
     end
 

data/lib/cancan/active_record_additions.rb

@@ -20,12 +20,11 @@ module CanCan
       # Here only the articles which the user can update are returned. This
       # internally uses Ability#conditions method, see that for more information.
       def accessible_by(ability, action = :read)
-        conditions = ability.conditions(action, self, :tableize => true) || {:id => nil}
-        joins = ability.association_joins(action, self)
+        query = ability.query(action, self)
         if respond_to? :where
-          where(conditions).joins(joins)
+          where(query.conditions).joins(query.joins)
         else
-          scoped(:conditions => conditions, :joins => joins)
+          scoped(:conditions => query.conditions, :joins => query.joins)
         end
       end
     end

data/lib/cancan/can_definition.rb

@@ -3,9 +3,9 @@ module CanCan
   # it holds the information about a "can" call made on Ability and provides
   # helpful methods to determine permission checking and conditions hash generation.
   class CanDefinition # :nodoc:
-    include ActiveSupport::Inflector
-    attr_reader :block
-    
+    attr_reader :base_behavior, :actions
+    attr_writer :expanded_actions
+
     # The first argument when initializing is the base_behavior which is a true/false
     # value. True for "can" and false for "cannot". The next two arguments are the action
     # and subject respectively (such as :read, @project). The third argument is a hash
@@ -18,51 +18,47 @@ module CanCan
       @block = block
     end
 
-    # Accepts a hash of aliased actions and returns an array of actions which match.
-    # This should be called before "matches?" and other checking methods since they
-    # rely on the actions to be expanded.
-    def expand_actions(aliased_actions)
-      @expanded_actions = @actions.map do |action|
-        aliased_actions[action] ? [action, *aliased_actions[action]] : action
-      end.flatten
-    end
-
-    def matches?(action, subject)
+    # Matches both the subject and action, not necessarily the conditions
+    def relevant?(action, subject)
       matches_action?(action) && matches_subject?(subject)
     end
 
-    def can?(action, subject, extra_args)
-      result = can_without_base_behavior?(action, subject, extra_args)
-      @base_behavior ? result : !result
+    # Matches the block or conditions hash
+    def matches_conditions?(action, subject, extra_args)
+      if @block
+        call_block(action, subject, extra_args)
+      elsif @conditions.kind_of?(Hash) && subject.class != Class
+        matches_conditions_hash?(subject)
+      else
+        true
+      end
     end
 
-    # Returns a hash of conditions. If the ":tableize => true" option is passed
-    # it will pluralize the association conditions to match the table name.
-    def conditions(options = {})
-      if options[:tableize] && @conditions.kind_of?(Hash)
+    # Returns a hash of conditions, pluralizing the table names
+    def tableized_conditions
+      if @conditions
         @conditions.inject({}) do |tableized_conditions, (name, value)|
-          name = tableize(name).to_sym if value.kind_of? Hash
+          name = name.to_s.tableize.to_sym if value.kind_of? Hash
           tableized_conditions[name] = value
           tableized_conditions
         end
-      else
-        @conditions
       end
     end
 
-    def association_joins(conditions = @conditions)
-      joins = []
-      conditions.each do |name, value|
-        if value.kind_of? Hash
-          nested = association_joins(value)
-          if nested
-            joins << {name => nested}
-          else
-            joins << name
-          end
-        end
+    def only_block?
+      conditions_empty? && !@block.nil?
+    end
+
+    def conditions_empty?
+      @conditions == {} || @conditions.nil?
+    end
+
+    def associations_hash(conditions = @conditions)
+      hash = {}
+      conditions.map do |name, value|
+        hash[name] = associations_hash(value) if value.kind_of? Hash
       end
-      joins unless joins.empty?
+      hash
     end
 
     private
@@ -72,27 +68,21 @@ module CanCan
     end
 
     def matches_subject?(subject)
-      @subjects.include?(:all) || @subjects.include?(subject) || @subjects.any? { |sub| sub.kind_of?(Class) && subject.kind_of?(sub) }
+      @subjects.include?(:all) || @subjects.include?(subject) || matches_subject_class?(subject)
     end
 
-    def can_without_base_behavior?(action, subject, extra_args)
-      if @block
-        call_block(action, subject, extra_args)
-      elsif @conditions && subject.class != Class
-        matches_conditions? subject
-      else
-        true
-      end
+    def matches_subject_class?(subject)
+      @subjects.any? { |sub| sub.kind_of?(Class) && (subject.kind_of?(sub) || subject.kind_of?(Class) && subject.ancestors.include?(sub)) }
     end
 
-    def matches_conditions?(subject, conditions = @conditions)
+    def matches_conditions_hash?(subject, conditions = @conditions)
       conditions.all? do |name, value|
         attribute = subject.send(name)
         if value.kind_of?(Hash)
           if attribute.kind_of? Array
-            attribute.any? { |element| matches_conditions? element, value }
+            attribute.any? { |element| matches_conditions_hash? element, value }
           else
-            matches_conditions? attribute, value
+            matches_conditions_hash? attribute, value
           end
         elsif value.kind_of?(Array) || value.kind_of?(Range)
           value.include? attribute

data/lib/cancan/controller_additions.rb

@@ -11,11 +11,11 @@ module CanCan
       #     load_and_authorize_resource
       #   end
       #
-      def load_and_authorize_resource(options = {})
-        ResourceAuthorization.add_before_filter(self, :load_and_authorize_resource, options)
+      def load_and_authorize_resource(*args)
+        ControllerResource.add_before_filter(self, :load_and_authorize_resource, *args)
       end
 
-      # Sets up a before filter which loads the appropriate model resource into an instance variable.
+      # Sets up a before filter which loads the model resource into an instance variable.
       # For example, given an ArticlesController it will load the current article into the @article
       # instance variable. It does this by either calling Article.find(params[:id]) or
       # Article.new(params[:article]) depending upon the action. It does nothing for the "index"
@@ -41,6 +41,20 @@ module CanCan
       #     end
       #   end
       #
+      # If a name is provided which does not match the controller it assumes it is a parent resource. Child
+      # resources can then be loaded through it.
+      #
+      #   class BooksController < ApplicationController
+      #     load_resource :author
+      #     load_resource :book, :through => :author
+      #   end
+      #
+      # Here the author resource will be loaded before each action using params[:author_id]. The book resource
+      # will then be loaded through the @author instance variable.
+      #
+      # That first argument is optional and will default to the singular name of the controller.
+      # A hash of options (see below) can also be passed to this method to further customize it.
+      #
       # See load_and_authorize_resource to automatically authorize the resource too.
       #
       # Options:
@@ -50,27 +64,30 @@ module CanCan
       # [:+except+]
       #   Does not apply before filter to given actions.
       #
-      # [:+nested+]
-      #   Specify which resource this is nested under.
+      # [:+through+]
+      #   Load this resource through another one. This should match the name of the parent instance variable.
       #
-      #     load_resource :nested => :author
+      # [:+singleton+]
+      #   Pass +true+ if this is a singleton resource through a +has_one+ association.
       #
-      #   Deep nesting can be defined in an array.
+      # [:+parent+]
+      #   True or false depending on if the resource is considered a parent resource. This defaults to +true+ if a resource
+      #   name is given which does not match the controller.
       #
-      #     load_resource :nested => [:publisher, :author]
+      # [:+class+]
+      #   The class to use for the model (string or constant).
       #
-      # [:+name+]
-      #   The name of the resource if it cannot be determined from controller (string or symbol).
+      # [:+instance_name+]
+      #   The name of the instance variable to load the resource into.
       #
-      #     load_resource :name => :article
+      # [:+find_by+]
+      #   Find using a different attribute other than id. For example.
       #
-      # [:+resource+]
-      #   The class to use for the model (string or constant).
+      #     load_resource :find_by => :permalink # will use find_by_permlink!(params[:id])
       #
       # [:+collection+]
       #   Specify which actions are resource collection actions in addition to :+index+. This
-      #   is usually not necessary because it will try to guess depending on if an :+id+
-      #   is present in +params+.
+      #   is usually not necessary because it will try to guess depending on if the id param is present.
       #
       #     load_resource :collection => [:sort, :list]
       #
@@ -81,11 +98,11 @@ module CanCan
       #
       #     load_resource :new => :build
       #
-      def load_resource(options = {})
-        ResourceAuthorization.add_before_filter(self, :load_resource, options)
+      def load_resource(*args)
+        ControllerResource.add_before_filter(self, :load_resource, *args)
       end
 
-      # Sets up a before filter which authorizes the current resource using the instance variable.
+      # Sets up a before filter which authorizes the resource using the instance variable.
       # For example, if you have an ArticlesController it will check the @article instance variable
       # and ensure the user can perform the current action on it. Under the hood it is doing
       # something like the following.
@@ -98,6 +115,19 @@ module CanCan
       #     authorize_resource
       #   end
       #
+      # If you pass in the name of a resource which does not match the controller it will assume
+      # it is a parent resource.
+      #
+      #   class BooksController < ApplicationController
+      #     authorize_resource :author
+      #     authorize_resource :book
+      #   end
+      #
+      # Here it will authorize :+show+, @+author+ on every action before authorizing the book.
+      #
+      # That first argument is optional and will default to the singular name of the controller.
+      # A hash of options (see below) can also be passed to this method to further customize it.
+      #
       # See load_and_authorize_resource to automatically load the resource too.
       #
       # Options:
@@ -107,17 +137,19 @@ module CanCan
       # [:+except+]
       #   Does not apply before filter to given actions.
       #
-      # [:+name+]
-      #   The name of the resource if it cannot be determined from controller (string or symbol).
+      # [:+parent+]
+      #   True or false depending on if the resource is considered a parent resource. This defaults to +true+ if a resource
+      #   name is given which does not match the controller.
       #
-      #     load_resource :name => :article
+      # [:+class+]
+      #   The class to use for the model (string or constant). This passed in when the instance variable is not set.
+      #   Pass +false+ if there is no associated class for this resource and it will use a symbol of the resource name.
       #
-      # [:+resource+]
-      #   The class to use for the model (string or constant). Alternatively pass a symbol
-      #   to represent a resource which does not have a class.
+      # [:+instance_name+]
+      #   The name of the instance variable for this resource.
       #
-      def authorize_resource(options = {})
-        ResourceAuthorization.add_before_filter(self, :authorize_resource, options)
+      def authorize_resource(*args)
+        ControllerResource.add_before_filter(self, :authorize_resource, *args)
       end
     end