Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 312 lines (287 sloc) 11.101 kB
0cfb8c7 @ryanb adding basic ability module
authored
1 module CanCan
dfd84a1 @ryanb improving inline documentation
authored
2
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
3 # This module is designed to be included into an Ability class. This will
4 # provide the "can" methods for defining and checking abilities.
dfd84a1 @ryanb improving inline documentation
authored
5 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
6 # class Ability
7 # include CanCan::Ability
8 #
9 # def initialize(user)
10 # if user.admin?
11 # can :manage, :all
12 # else
13 # can :read, :all
14 # end
15 # end
16 # end
dfd84a1 @ryanb improving inline documentation
authored
17 #
0cfb8c7 @ryanb adding basic ability module
authored
18 module Ability
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
19 # Check if the user has permission to perform a given action on an object.
dfd84a1 @ryanb improving inline documentation
authored
20 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
21 # can? :destroy, @project
dfd84a1 @ryanb improving inline documentation
authored
22 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
23 # You can also pass the class instead of an instance (if you don't have one handy).
dfd84a1 @ryanb improving inline documentation
authored
24 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
25 # can? :create, Project
dfd84a1 @ryanb improving inline documentation
authored
26 #
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
27 # Nested resources can be passed through a hash, this way conditions which are
28 # dependent upon the association will work when using a class.
29 #
30 # can? :create, @category => Project
31 #
510cf50 @ryanb adding documentation for passing additional arguments to can?
authored
32 # Any additional arguments will be passed into the "can" block definition. This
33 # can be used to pass more information about the user's request for example.
dfd84a1 @ryanb improving inline documentation
authored
34 #
510cf50 @ryanb adding documentation for passing additional arguments to can?
authored
35 # can? :create, Project, request.remote_ip
dfd84a1 @ryanb improving inline documentation
authored
36 #
510cf50 @ryanb adding documentation for passing additional arguments to can?
authored
37 # can :create Project do |project, remote_ip|
38 # # ...
39 # end
dfd84a1 @ryanb improving inline documentation
authored
40 #
41 # Not only can you use the can? method in the controller and view (see ControllerAdditions),
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
42 # but you can also call it directly on an ability instance.
dfd84a1 @ryanb improving inline documentation
authored
43 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
44 # ability.can? :destroy, @project
dfd84a1 @ryanb improving inline documentation
authored
45 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
46 # This makes testing a user's abilities very easy.
dfd84a1 @ryanb improving inline documentation
authored
47 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
48 # def test "user can only destroy projects which he owns"
49 # user = User.new
50 # ability = Ability.new(user)
51 # assert ability.can?(:destroy, Project.new(:user => user))
52 # assert ability.cannot?(:destroy, Project.new)
53 # end
dfd84a1 @ryanb improving inline documentation
authored
54 #
55 # Also see the RSpec Matchers to aid in testing.
d9f3c8b @ryanb renaming noun to subject internally
authored
56 def can?(action, subject, *extra_args)
37c1491 @ryanb renaming CanDefinition to Rule
authored
57 match = relevant_rules_for_match(action, subject).detect do |rule|
58 rule.matches_conditions?(action, subject, extra_args)
7d7d249 @funny-falcon passing throw matching rules with not matching conditions
funny-falcon authored
59 end
6084814 @ryanb refactoring can definition matching behavior
authored
60 match ? match.base_behavior : false
0cfb8c7 @ryanb adding basic ability module
authored
61 end
dfd84a1 @ryanb improving inline documentation
authored
62
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
63 # Convenience method which works the same as "can?" but returns the opposite value.
dfd84a1 @ryanb improving inline documentation
authored
64 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
65 # cannot? :destroy, @project
dfd84a1 @ryanb improving inline documentation
authored
66 #
0f49b54 @ryanb adding 'cannot?' method which performs opposite check of 'can?' - clo…
authored
67 def cannot?(*args)
68 !can?(*args)
69 end
dfd84a1 @ryanb improving inline documentation
authored
70
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
71 # Defines which abilities are allowed using two arguments. The first one is the action
72 # you're setting the permission for, the second one is the class of object you're setting it on.
dfd84a1 @ryanb improving inline documentation
authored
73 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
74 # can :update, Article
dfd84a1 @ryanb improving inline documentation
authored
75 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
76 # You can pass an array for either of these parameters to match any one.
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
77 # Here the user has the ability to update or destroy both articles and comments.
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
78 #
79 # can [:update, :destroy], [Article, Comment]
80 #
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
81 # You can pass :all to match any object and :manage to match any action. Here are some examples.
82 #
83 # can :manage, :all
84 # can :update, :all
85 # can :manage, Project
dfd84a1 @ryanb improving inline documentation
authored
86 #
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
87 # You can pass a hash of conditions as the third argument. Here the user can only see active projects which he owns.
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
88 #
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
authored
89 # can :read, Project, :active => true, :user_id => user.id
dfd84a1 @ryanb improving inline documentation
authored
90 #
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
91 # See ActiveRecordAdditions#accessible_by for how to use this in database queries. These conditions
92 # are also used for initial attributes when building a record in ControllerAdditions#load_resource.
dfd84a1 @ryanb improving inline documentation
authored
93 #
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
94 # If the conditions hash does not give you enough control over defining abilities, you can use a block
95 # along with any Ruby code you want.
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
96 #
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
authored
97 # can :update, Project do |project|
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
98 # project.groups.include?(user.group)
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
99 # end
dfd84a1 @ryanb improving inline documentation
authored
100 #
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
authored
101 # If the block returns true then the user has that :update ability for that project, otherwise he
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
102 # will be denied access. The downside to using a block is that it cannot be used to generate
103 # conditions for database queries.
dfd84a1 @ryanb improving inline documentation
authored
104 #
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
105 # You can pass custom objects into this "can" method, this is usually done with a symbol
106 # and is useful if a class isn't available to define permissions on.
dfd84a1 @ryanb improving inline documentation
authored
107 #
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
108 # can :read, :stats
109 # can? :read, :stats # => true
dfd84a1 @ryanb improving inline documentation
authored
110 #
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
111 # IMPORTANT: Neither a hash of conditions or a block will be used when checking permission on a class.
dfd84a1 @ryanb improving inline documentation
authored
112 #
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
113 # can :update, Project, :priority => 3
114 # can? :update, Project # => true
dfd84a1 @ryanb improving inline documentation
authored
115 #
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
116 # If you pass no arguments to +can+, the action, class, and object will be passed to the block and the
117 # block will always be executed. This allows you to override the full behavior if the permissions are
118 # defined in an external source such as the database.
dfd84a1 @ryanb improving inline documentation
authored
119 #
bf9b8ad @ryanb filling in some inline documentation for 1.4
authored
120 # can do |action, object_class, object|
121 # # check the database and return true/false
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
122 # end
dfd84a1 @ryanb improving inline documentation
authored
123 #
66314a8 @ryanb support no arguments to 'can' definition which always calls block
authored
124 def can(action = nil, subject = nil, conditions = nil, &block)
37c1491 @ryanb renaming CanDefinition to Rule
authored
125 rules << Rule.new(true, action, subject, conditions, block)
d4405e6 @ryanb adding cannot method to define which abilities cannot be done - close…
authored
126 end
dfd84a1 @ryanb improving inline documentation
authored
127
128 # Defines an ability which cannot be done. Accepts the same arguments as "can".
129 #
d4405e6 @ryanb adding cannot method to define which abilities cannot be done - close…
authored
130 # can :read, :all
131 # cannot :read, Comment
dfd84a1 @ryanb improving inline documentation
authored
132 #
d4405e6 @ryanb adding cannot method to define which abilities cannot be done - close…
authored
133 # A block can be passed just like "can", however if the logic is complex it is recommended
134 # to use the "can" method.
dfd84a1 @ryanb improving inline documentation
authored
135 #
d4405e6 @ryanb adding cannot method to define which abilities cannot be done - close…
authored
136 # cannot :read, Product do |product|
137 # product.invisible?
138 # end
dfd84a1 @ryanb improving inline documentation
authored
139 #
66314a8 @ryanb support no arguments to 'can' definition which always calls block
authored
140 def cannot(action = nil, subject = nil, conditions = nil, &block)
37c1491 @ryanb renaming CanDefinition to Rule
authored
141 rules << Rule.new(false, action, subject, conditions, block)
4b6f538 @ryanb moving can definition into ability instance instead of class, this re…
authored
142 end
dfd84a1 @ryanb improving inline documentation
authored
143
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
144 # Alias one or more actions into another one.
dfd84a1 @ryanb improving inline documentation
authored
145 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
146 # alias_action :update, :destroy, :to => :modify
147 # can :modify, Comment
dfd84a1 @ryanb improving inline documentation
authored
148 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
149 # Then :modify permission will apply to both :update and :destroy requests.
dfd84a1 @ryanb improving inline documentation
authored
150 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
151 # can? :update, Comment # => true
152 # can? :destroy, Comment # => true
dfd84a1 @ryanb improving inline documentation
authored
153 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
154 # This only works in one direction. Passing the aliased action into the "can?" call
155 # will not work because aliases are meant to generate more generic actions.
dfd84a1 @ryanb improving inline documentation
authored
156 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
157 # alias_action :update, :destroy, :to => :modify
158 # can :update, Comment
159 # can? :modify, Comment # => false
dfd84a1 @ryanb improving inline documentation
authored
160 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
161 # Unless that exact alias is used.
dfd84a1 @ryanb improving inline documentation
authored
162 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
163 # can :modify, Comment
164 # can? :modify, Comment # => true
dfd84a1 @ryanb improving inline documentation
authored
165 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
166 # The following aliases are added by default for conveniently mapping common controller actions.
dfd84a1 @ryanb improving inline documentation
authored
167 #
b9227eb @ryanb adding a lot of inline documentation to code for rdocs
authored
168 # alias_action :index, :show, :to => :read
169 # alias_action :new, :to => :create
170 # alias_action :edit, :to => :update
dfd84a1 @ryanb improving inline documentation
authored
171 #
5bd1a85 @ryanb little fixes to inline documentation (rdocs)
authored
172 # This way one can use params[:action] in the controller to determine the permission.
4b6f538 @ryanb moving can definition into ability instance instead of class, this re…
authored
173 def alias_action(*args)
174 target = args.pop[:to]
925274d @fl00r Fixing Segmentation fault on aliasing
fl00r authored
175 validate_target(target)
f99d506 @ryanb Append aliased actions (don't overwrite them) - closes #20
authored
176 aliased_actions[target] ||= []
177 aliased_actions[target] += args
4b6f538 @ryanb moving can definition into ability instance instead of class, this re…
authored
178 end
dfd84a1 @ryanb improving inline documentation
authored
179
925274d @fl00r Fixing Segmentation fault on aliasing
fl00r authored
180 # User shouldn't specify targets with names of real actions or it will cause Seg fault
181 def validate_target(target)
182 raise Error, "You can't specify target (#{target}) as alias because it is real action name" if aliased_actions.values.flatten.include? target
183 end
184
7d3b4cd @ryanb Adding clear_aliased_actions to Ability which removes previously defi…
authored
185 # Returns a hash of aliased actions. The key is the target and the value is an array of actions aliasing the key.
c40490d @ryanb refactoring ability can? method - closes #12
authored
186 def aliased_actions
187 @aliased_actions ||= default_alias_actions
188 end
dfd84a1 @ryanb improving inline documentation
authored
189
7d3b4cd @ryanb Adding clear_aliased_actions to Ability which removes previously defi…
authored
190 # Removes previously aliased actions including the defaults.
191 def clear_aliased_actions
192 @aliased_actions = {}
193 end
dfd84a1 @ryanb improving inline documentation
authored
194
af9e77a @ryanb adding initial active record adapter
authored
195 def model_adapter(model_class, action)
bbb02f7 @ryanb dynamically detect which model adapter to use given a class
authored
196 adapter_class = ModelAdapters::AbstractAdapter.adapter_class(model_class)
197 adapter_class.new(model_class, relevant_rules_for_query(action, model_class))
e200814 @ryanb adding joins clause to accessible_by when conditions are across assoc…
authored
198 end
25637bb @ryanb removing extra white space at end of lines
authored
199
a5f838a @ryanb use I18n for unauthorization messages - closes #103
authored
200 # See ControllerAdditions#authorize! for documentation.
201 def authorize!(action, subject, *args)
202 message = nil
203 if args.last.kind_of?(Hash) && args.last.has_key?(:message)
204 message = args.pop[:message]
205 end
206 if cannot?(action, subject, *args)
207 message ||= unauthorized_message(action, subject)
208 raise AccessDenied.new(message, action, subject)
209 end
1ac8099 @ryanb return subject passed to authorize! - closes #314
authored
210 subject
a5f838a @ryanb use I18n for unauthorization messages - closes #103
authored
211 end
212
213 def unauthorized_message(action, subject)
214 keys = unauthorized_message_keys(action, subject)
158c908 @ryanb adding action and subject variables to I18n unauthorized message - cl…
authored
215 variables = {:action => action.to_s}
ba99997 @ryanb add space in multiword model in I18n unauthorized message - closes #292
authored
216 variables[:subject] = (subject.class == Class ? subject : subject.class).to_s.underscore.humanize.downcase
158c908 @ryanb adding action and subject variables to I18n unauthorized message - cl…
authored
217 message = I18n.translate(nil, variables.merge(:scope => :unauthorized, :default => keys + [""]))
a5f838a @ryanb use I18n for unauthorization messages - closes #103
authored
218 message.blank? ? nil : message
219 end
220
a744377 @ryanb the new and create actions will now build the resource with attribute…
authored
221 def attributes_for(action, subject)
222 attributes = {}
37c1491 @ryanb renaming CanDefinition to Rule
authored
223 relevant_rules(action, subject).map do |rule|
224 attributes.merge!(rule.attributes_from_conditions) if rule.base_behavior
a744377 @ryanb the new and create actions will now build the resource with attribute…
authored
225 end
226 attributes
227 end
228
9d91545 @ryanb load the collection instance variable on index action - closes #137
authored
229 def has_block?(action, subject)
37c1491 @ryanb renaming CanDefinition to Rule
authored
230 relevant_rules(action, subject).any?(&:only_block?)
9d91545 @ryanb load the collection instance variable on index action - closes #137
authored
231 end
b0cec52 @ryanb adding a couple things to the changelog
authored
232
12037d7 @funny-falcon should not allow to can? when raw sql without block is present
funny-falcon authored
233 def has_raw_sql?(action, subject)
37c1491 @ryanb renaming CanDefinition to Rule
authored
234 relevant_rules(action, subject).any?(&:only_raw_sql?)
12037d7 @funny-falcon should not allow to can? when raw sql without block is present
funny-falcon authored
235 end
9d91545 @ryanb load the collection instance variable on index action - closes #137
authored
236
7797b37 @rogercampos Adding Ability#merge
rogercampos authored
237 def merge(ability)
238 ability.send(:rules).each do |rule|
239 rules << rule.dup
240 end
241 self
242 end
243
7d3b4cd @ryanb Adding clear_aliased_actions to Ability which removes previously defi…
authored
244 private
25637bb @ryanb removing extra white space at end of lines
authored
245
a5f838a @ryanb use I18n for unauthorization messages - closes #103
authored
246 def unauthorized_message_keys(action, subject)
247 subject = (subject.class == Class ? subject : subject.class).name.underscore unless subject.kind_of? Symbol
248 [subject, :all].map do |try_subject|
249 [aliases_for_action(action), :manage].flatten.map do |try_action|
250 :"#{try_action}.#{try_subject}"
251 end
252 end.flatten
253 end
254
255 # Accepts an array of actions and returns an array of actions which match.
cad4259 @ryanb supporting deeply nested aliases - closes #98
authored
256 # This should be called before "matches?" and other checking methods since they
257 # rely on the actions to be expanded.
258 def expand_actions(actions)
259 actions.map do |action|
260 aliased_actions[action] ? [action, *expand_actions(aliased_actions[action])] : action
261 end.flatten
262 end
dfd84a1 @ryanb improving inline documentation
authored
263
a5f838a @ryanb use I18n for unauthorization messages - closes #103
authored
264 # Given an action, it will try to find all of the actions which are aliased to it.
265 # This does the opposite kind of lookup as expand_actions.
266 def aliases_for_action(action)
267 results = [action]
268 aliased_actions.each do |aliased_action, actions|
269 results += aliases_for_action(aliased_action) if actions.include? action
270 end
271 results
272 end
273
37c1491 @ryanb renaming CanDefinition to Rule
authored
274 def rules
275 @rules ||= []
bbbc8a6 @ryanb refactoring much of Ability class into separate CanDefinition class
authored
276 end
dfd84a1 @ryanb improving inline documentation
authored
277
37c1491 @ryanb renaming CanDefinition to Rule
authored
278 # Returns an array of Rule instances which match the action and subject
6084814 @ryanb refactoring can definition matching behavior
authored
279 # This does not take into consideration any hash conditions or block statements
37c1491 @ryanb renaming CanDefinition to Rule
authored
280 def relevant_rules(action, subject)
281 rules.reverse.select do |rule|
282 rule.expanded_actions = expand_actions(rule.actions)
283 rule.relevant? action, subject
baeef0b @ryanb adding conditions behavior to Ability#can and fetch with Ability#cond…
authored
284 end
285 end
b0cec52 @ryanb adding a couple things to the changelog
authored
286
37c1491 @ryanb renaming CanDefinition to Rule
authored
287 def relevant_rules_for_match(action, subject)
288 relevant_rules(action, subject).each do |rule|
289 if rule.only_raw_sql?
12037d7 @funny-falcon should not allow to can? when raw sql without block is present
funny-falcon authored
290 raise Error, "The can? and cannot? call cannot be used with a raw sql 'can' definition. The checking code cannot be determined for #{action.inspect} #{subject.inspect}"
291 end
292 end
293 end
dfd84a1 @ryanb improving inline documentation
authored
294
37c1491 @ryanb renaming CanDefinition to Rule
authored
295 def relevant_rules_for_query(action, subject)
296 relevant_rules(action, subject).each do |rule|
297 if rule.only_block?
4fe44af @ryanb be more clear about blocks not working with accessible_by - closes #130
authored
298 raise Error, "The accessible_by call cannot be used with a block 'can' definition. The SQL cannot be determined for #{action.inspect} #{subject.inspect}"
a42e067 @ryanb extracting out Query class for generating sql conditions and associat…
authored
299 end
300 end
301 end
302
4b6f538 @ryanb moving can definition into ability instance instead of class, this re…
authored
303 def default_alias_actions
304 {
305 :read => [:index, :show],
306 :create => [:new],
307 :update => [:edit],
308 }
309 end
0cfb8c7 @ryanb adding basic ability module
authored
310 end
311 end
Something went wrong with that request. Please try again.