cancan 1.1.1 → 1.2.0

data/CHANGELOG.rdoc

@@ -1,3 +1,18 @@
+1.2.0 (July 16, 2010)
+
+* Load nested parent resources on collection actions such as "index" (thanks dohzya)
+
+* Adding :name option to load_and_authorize_resource if it does not match controller - see issue #65
+
+* Fixing issue when using accessible_by with nil can conditions (thanks jrallison) - see issue #66
+
+* Pluralize table name for belongs_to associations in can conditions hash (thanks logandk) - see issue #62
+
+* Support has_many association or arrays in can conditions hash
+
+* Adding joins clause to accessible_by when conditions are across associations
+
+
 1.1.1 (April 17, 2010)
 
 * Fixing behavior in Rails 3 by properly initializing ResourceAuthorization

data/lib/cancan.rb

@@ -1,4 +1,5 @@
 require 'cancan/ability'
+require 'cancan/can_definition'
 require 'cancan/controller_resource'
 require 'cancan/resource_authorization'
 require 'cancan/controller_additions'

data/lib/cancan/ability.rb

@@ -1,8 +1,8 @@
 module CanCan
-  
+
   # This module is designed to be included into an Ability class. This will
   # provide the "can" methods for defining and checking abilities.
-  # 
+  #
   #   class Ability
   #     include CanCan::Ability
   #
@@ -14,206 +14,216 @@ module CanCan
   #       end
   #     end
   #   end
-  # 
+  #
   module Ability
-    # Use to check the user's permission for a given action and object.
-    # 
+    # Use to check if the user has permission to perform a given action on an object.
+    #
     #   can? :destroy, @project
-    # 
+    #
     # You can also pass the class instead of an instance (if you don't have one handy).
-    # 
+    #
     #   can? :create, Project
-    # 
+    #
     # Any additional arguments will be passed into the "can" block definition. This
     # can be used to pass more information about the user's request for example.
-    # 
+    #
     #   can? :create, Project, request.remote_ip
-    #   
+    #
     #   can :create Project do |project, remote_ip|
     #     # ...
     #   end
-    # 
-    # Not only can you use the can? method in the controller and view (see ControllerAdditions), 
+    #
+    # Not only can you use the can? method in the controller and view (see ControllerAdditions),
     # but you can also call it directly on an ability instance.
-    # 
+    #
     #   ability.can? :destroy, @project
-    # 
+    #
     # This makes testing a user's abilities very easy.
-    # 
+    #
     #   def test "user can only destroy projects which he owns"
     #     user = User.new
     #     ability = Ability.new(user)
     #     assert ability.can?(:destroy, Project.new(:user => user))
     #     assert ability.cannot?(:destroy, Project.new)
     #   end
-    # 
+    #
+    # Also see the RSpec Matchers to aid in testing.
     def can?(action, subject, *extra_args)
-      matching_can_definition(action, subject) do |base_behavior, defined_actions, defined_subjects, defined_conditions, defined_block|
-        result = can_perform_action?(action, subject, defined_actions, defined_subjects, defined_conditions, defined_block, extra_args)
-        return base_behavior ? result : !result
-      end
-      false
+      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)
     end
-    
+
     # Convenience method which works the same as "can?" but returns the opposite value.
-    # 
+    #
     #   cannot? :destroy, @project
-    # 
+    #
     def cannot?(*args)
       !can?(*args)
     end
-    
+
     # Defines which abilities are allowed using two arguments. The first one is the action
     # you're setting the permission for, the second one is the class of object you're setting it on.
-    # 
+    #
     #   can :update, Article
-    # 
+    #
     # You can pass an array for either of these parameters to match any one.
     #
     #   can [:update, :destroy], [Article, Comment]
     #
     # In this case the user has the ability to update or destroy both articles and comments.
-    # 
+    #
     # You can pass a hash of conditions as the third argument.
     #
     #   can :read, Project, :active => true, :user_id => user.id
-    # 
-    # Here the user can only see active projects which he owns. See ControllerAdditions#conditions for a way to
-    # use this in database queries.
-    # 
+    #
+    # Here the user can only see active projects which he owns. See ActiveRecordAdditions#accessible_by
+    # for how to use this in database queries.
+    #
     # If the conditions hash does not give you enough control over defining abilities, you can use a block to
     # write any Ruby code you want.
     #
     #   can :update, Project do |project|
     #     project && project.groups.include?(user.group)
     #   end
-    # 
+    #
     # If the block returns true then the user has that :update ability for that project, otherwise he
     # will be denied access. It's possible for the passed in model to be nil if one isn't specified,
     # so be sure to take that into consideration.
-    # 
+    #
     # The downside to using a block is that it cannot be used to generate conditions for database queries.
-    # 
+    #
     # You can pass :all to reference every type of object. In this case the object type will be passed
     # into the block as well (just in case object is nil).
-    # 
+    #
     #   can :read, :all do |object_class, object|
     #     object_class != Order
     #   end
-    # 
+    #
     # Here the user has permission to read all objects except orders.
-    # 
-    # You can also pass :manage as the action which will match any action. In this case the action is 
+    #
+    # You can also pass :manage as the action which will match any action. In this case the action is
     # passed to the block.
-    # 
+    #
     #   can :manage, Comment do |action, comment|
     #     action != :destroy
     #   end
-    # 
+    #
     # You can pass custom objects into this "can" method, this is usually done through a symbol
     # and is useful if a class isn't available to define permissions on.
-    # 
+    #
     #   can :read, :stats
     #   can? :read, :stats # => true
-    # 
+    #
     def can(action, subject, conditions = nil, &block)
-      @can_definitions ||= []
-      @can_definitions << [true, action, subject, conditions, block]
+      can_definitions << CanDefinition.new(true, action, subject, conditions, block)
     end
-    
-    # Define an ability which cannot be done. Accepts the same arguments as "can".
-    # 
+
+    # Defines an ability which cannot be done. Accepts the same arguments as "can".
+    #
     #   can :read, :all
     #   cannot :read, Comment
-    # 
+    #
     # A block can be passed just like "can", however if the logic is complex it is recommended
     # to use the "can" method.
-    # 
+    #
     #   cannot :read, Product do |product|
     #     product.invisible?
     #   end
-    # 
+    #
     def cannot(action, subject, conditions = nil, &block)
-      @can_definitions ||= []
-      @can_definitions << [false, action, subject, conditions, block]
+      can_definitions << CanDefinition.new(false, action, subject, conditions, block)
     end
-    
+
     # Alias one or more actions into another one.
-    # 
+    #
     #   alias_action :update, :destroy, :to => :modify
     #   can :modify, Comment
-    # 
+    #
     # Then :modify permission will apply to both :update and :destroy requests.
-    # 
+    #
     #   can? :update, Comment # => true
     #   can? :destroy, Comment # => true
-    # 
+    #
     # This only works in one direction. Passing the aliased action into the "can?" call
     # will not work because aliases are meant to generate more generic actions.
-    # 
+    #
     #   alias_action :update, :destroy, :to => :modify
     #   can :update, Comment
     #   can? :modify, Comment # => false
-    # 
+    #
     # Unless that exact alias is used.
-    # 
+    #
     #   can :modify, Comment
     #   can? :modify, Comment # => true
-    # 
+    #
     # The following aliases are added by default for conveniently mapping common controller actions.
-    # 
+    #
     #   alias_action :index, :show, :to => :read
     #   alias_action :new, :to => :create
     #   alias_action :edit, :to => :update
-    # 
+    #
     # This way one can use params[:action] in the controller to determine the permission.
     def alias_action(*args)
       target = args.pop[:to]
       aliased_actions[target] ||= []
       aliased_actions[target] += args
     end
-    
+
     # Returns a hash of aliased actions. The key is the target and the value is an array of actions aliasing the key.
     def aliased_actions
       @aliased_actions ||= default_alias_actions
     end
-    
+
     # Removes previously aliased actions including the defaults.
     def clear_aliased_actions
       @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)
-      matching_can_definition(action, subject) do |base_behavior, defined_actions, defined_subjects, defined_conditions, defined_block|
-        raise Error, "Cannot determine ability conditions from block for #{action.inspect} #{subject.inspect}" if defined_block
-        return defined_conditions || {}
+    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
-      false
     end
-    
+
     private
-    
-    def matching_can_definition(action, subject, &block)
-      (@can_definitions || []).reverse.each do |base_behavior, defined_action, defined_subject, defined_conditions, defined_block|
-        defined_actions = expand_actions(defined_action)
-        defined_subjects = [defined_subject].flatten
-        if includes_action?(defined_actions, action) && includes_subject?(defined_subjects, subject)
-          return block.call(base_behavior, defined_actions, defined_subjects, defined_conditions, defined_block)
-        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
       end
     end
-    
+
     def default_alias_actions
       {
         :read => [:index, :show],
@@ -221,55 +231,5 @@ module CanCan
         :update => [:edit],
       }
     end
-    
-    def expand_actions(actions)
-      [actions].flatten.map do |action|
-        if aliased_actions[action]
-          [action, *aliased_actions[action]]
-        else
-          action
-        end
-      end.flatten
-    end
-    
-    def can_perform_action?(action, subject, defined_actions, defined_subjects, defined_conditions, defined_block, extra_args)
-      if defined_block
-        block_args = []
-        block_args << action if defined_actions.include?(:manage)
-        block_args << (subject.class == Class ? subject : subject.class) if defined_subjects.include?(:all)
-        block_args << (subject.class == Class ? nil : subject)
-        block_args += extra_args
-        defined_block.call(*block_args)
-      elsif defined_conditions
-        if subject.class == Class
-          true
-        else
-          matches_conditions? subject, defined_conditions
-        end
-      else
-        true
-      end
-    end
-    
-    def matches_conditions?(subject, defined_conditions)
-      defined_conditions.all? do |name, value|
-        attribute = subject.send(name)
-        if value.kind_of?(Hash)
-          matches_conditions? attribute, value
-        elsif value.kind_of?(Array) || value.kind_of?(Range)
-          value.include? attribute
-        else
-          attribute == value
-        end
-      end
-    end
-    
-    def includes_action?(actions, action)
-      actions.include?(:manage) || actions.include?(action)
-    end
-    
-    def includes_subject?(subjects, subject)
-      subjects.include?(:all) || subjects.include?(subject) || subjects.any? { |c| c.kind_of?(Class) && subject.kind_of?(c) }
-    end
   end
 end

data/lib/cancan/active_record_additions.rb

@@ -1,5 +1,5 @@
 module CanCan
-  # This module is automatically included into all Active Record.
+  # This module is automatically included into all Active Record models.
   module ActiveRecordAdditions
     module ClassMethods
       # Returns a scope which fetches only the records that the passed ability
@@ -7,28 +7,29 @@ module CanCan
       # is usually called from a controller and passed the +current_ability+.
       #
       #   @articles = Article.accessible_by(current_ability)
-      # 
+      #
       # Here only the articles which the user is able to read will be returned.
       # If the user does not have permission to read any articles then an empty
       # result is returned. Since this is a scope it can be combined with any
       # other scopes or pagination.
-      # 
+      #
       # An alternative action can optionally be passed as a second argument.
-      # 
+      #
       #   @articles = Article.accessible_by(current_ability, :update)
-      # 
+      #
       # 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) || {:id => nil}
+        conditions = ability.conditions(action, self, :tableize => true) || {:id => nil}
+        joins = ability.association_joins(action, self)
         if respond_to? :where
-          where(conditions)
+          where(conditions).joins(joins)
         else
-          scoped(:conditions => conditions)
+          scoped(:conditions => conditions, :joins => joins)
         end
       end
     end
-    
+
     def self.included(base)
       base.extend ClassMethods
     end

data/lib/cancan/can_definition.rb

@@ -0,0 +1,114 @@
+module CanCan
+  # This class is used internally and should only be called through Ability.
+  # 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
+    
+    # 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
+    # of conditions and the last one is the block passed to the "can" call.
+    def initialize(base_behavior, action, subject, conditions, block)
+      @base_behavior = base_behavior
+      @actions = [action].flatten
+      @subjects = [subject].flatten
+      @conditions = conditions || {}
+      @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_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
+    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)
+        @conditions.inject({}) do |tableized_conditions, (name, value)|
+          name = tableize(name).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
+      end
+      joins unless joins.empty?
+    end
+
+    private
+
+    def matches_action?(action)
+      @expanded_actions.include?(:manage) || @expanded_actions.include?(action)
+    end
+
+    def matches_subject?(subject)
+      @subjects.include?(:all) || @subjects.include?(subject) || @subjects.any? { |sub| sub.kind_of?(Class) && subject.kind_of?(sub) }
+    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
+    end
+
+    def matches_conditions?(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 }
+          else
+            matches_conditions? attribute, value
+          end
+        elsif value.kind_of?(Array) || value.kind_of?(Range)
+          value.include? attribute
+        else
+          attribute == value
+        end
+      end
+    end
+
+    def call_block(action, subject, extra_args)
+      block_args = []
+      block_args << action if @expanded_actions.include?(:manage)
+      block_args << (subject.class == Class ? subject : subject.class) if @subjects.include?(:all)
+      block_args << (subject.class == Class ? nil : subject)
+      block_args += extra_args
+      @block.call(*block_args)
+    end
+  end
+end