Class: DeclarativePolicy::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/declarative_policy/base.rb

Direct Known Subclasses

BasePolicy

Defined Under Namespace

Classes: AbilityMap

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(user, subject, opts = {}) ⇒ Base

Returns a new instance of Base.


217
218
219
220
221
 
# File 'lib/declarative_policy/base.rb', line 217

def initialize(user, subject, opts = {})
  @user = user
  @subject = subject
  @cache = opts[:cache] || {}
end

Instance Attribute Details

#subject ⇒ Object (readonly)

A policy object contains a specific user and subject on which to compute abilities. For this reason it's sometimes called “context” within the framework.

It also stores a reference to the cache, so it can be used to cache computations by e.g. ManifestCondition.


216
217
218
 
# File 'lib/declarative_policy/base.rb', line 216

def subject
  @subject
end

#user ⇒ Object (readonly)

A policy object contains a specific user and subject on which to compute abilities. For this reason it's sometimes called “context” within the framework.

It also stores a reference to the cache, so it can be used to cache computations by e.g. ManifestCondition.


216
217
218
 
# File 'lib/declarative_policy/base.rb', line 216

def user
  @user
end

Class Method Details

.ability_map ⇒ Object

The `own_ability_map` vs `ability_map` distinction is used so that the data structure is properly inherited - with subclasses recursively merging their parent class.

This pattern is also used for conditions, global_actions, and delegations.


41
42
43
44
45
46
47
 
# File 'lib/declarative_policy/base.rb', line 41

def ability_map
  if self == Base
    own_ability_map
  else
    superclass.ability_map.merge(own_ability_map)
  end
end

.condition(name, opts = {}, &value) ⇒ Object

Declares a condition. It gets stored in `own_conditions`, and generates a query method based on the condition's name.


177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/declarative_policy/base.rb', line 177

def condition(name, opts = {}, &value)
  name = name.to_sym

  opts = last_options!.merge(opts)
  opts[:context_key] ||= self.name

  condition = Condition.new(name, opts, &value)

  self.own_conditions[name] = condition

  define_method(:"#{name}?") { condition(name).pass? }
end

.conditions ⇒ Object

an inheritable map of conditions, by name


54
55
56
57
58
59
60
 
# File 'lib/declarative_policy/base.rb', line 54

def conditions
  if self == Base
    own_conditions
  else
    superclass.conditions.merge(own_conditions)
  end
end

.configuration_for(ability) ⇒ Object

all the [rule, action] pairs that apply to a particular ability. we combine the specific ones looked up in ability_map with the global ones.


98
99
100
 
# File 'lib/declarative_policy/base.rb', line 98

def configuration_for(ability)
  ability_map.actions(ability) + global_actions
end

.delegate(name = nil, &delegation_block) ⇒ Object

declaration methods ###


104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/declarative_policy/base.rb', line 104

def delegate(name = nil, &delegation_block)
  if name.nil?
    @delegate_name_counter ||= 0
    @delegate_name_counter += 1
    name = :"anonymous_#{@delegate_name_counter}"
  end

  name = name.to_sym

  if delegation_block.nil?
    delegation_block = proc { @subject.__send__(name) } # rubocop:disable GitlabSecurity/PublicSend
  end

  own_delegations[name] = delegation_block
end

.delegations ⇒ Object

an inheritable map of delegations, indexed by name (which may be autogenerated)


83
84
85
86
87
88
89
 
# File 'lib/declarative_policy/base.rb', line 83

def delegations
  if self == Base
    own_delegations
  else
    superclass.delegations.merge(own_delegations)
  end
end

.desc(description) ⇒ Object

Declare a description for the following condition. Currently unused, but opens the potential for explaining to users why they were or were not able to do something.


159
160
161
 
# File 'lib/declarative_policy/base.rb', line 159

def desc(description)
  last_options[:description] = description
end

.enable_when(abilities, rule) ⇒ Object

These next three methods are mainly called from PolicyDsl, and are responsible for “inverting” the relationship between an ability and a rule. We store in `ability_map` a map of abilities to rules that affect them, together with a symbol indicating :prevent or :enable.


195
196
197
 
# File 'lib/declarative_policy/base.rb', line 195

def enable_when(abilities, rule)
  abilities.each { |a| own_ability_map.enable(a, rule) }
end

.global_actions ⇒ Object

a list of global actions, generated by `prevent_all`. these aren't stored in `ability_map` because they aren't indexed by a particular ability.


69
70
71
72
73
74
75
 
# File 'lib/declarative_policy/base.rb', line 69

def global_actions
  if self == Base
    own_global_actions
  else
    superclass.global_actions + own_global_actions
  end
end

.last_options ⇒ Object

A hash in which to store calls to `desc` and `with_scope`, etc.


147
148
149
 
# File 'lib/declarative_policy/base.rb', line 147

def last_options
  @last_options ||= {}.with_indifferent_access
end

.last_options! ⇒ Object

retrieve and zero out the previously set options (used in .condition)


152
153
154
 
# File 'lib/declarative_policy/base.rb', line 152

def last_options!
  last_options.tap { @last_options = nil }
end

.overrides(*names) ⇒ Object

Declare that the given abilities should not be read from delegates.

This is useful if you have an ability that you want to define differently in a policy than in a delegated policy, but still want to delegate all other abilities.

example:

delegate { @subect.parent }

overrides :drive_car, :watch_tv


132
133
134
135
 
# File 'lib/declarative_policy/base.rb', line 132

def overrides(*names)
  @overrides ||= [].to_set
  @overrides.merge(names)
end

.own_ability_map ⇒ Object 


49
50
51
 
# File 'lib/declarative_policy/base.rb', line 49

def own_ability_map
  @own_ability_map ||= AbilityMap.new
end

.own_conditions ⇒ Object 


62
63
64
 
# File 'lib/declarative_policy/base.rb', line 62

def own_conditions
  @own_conditions ||= {}
end

.own_delegations ⇒ Object 


91
92
93
 
# File 'lib/declarative_policy/base.rb', line 91

def own_delegations
  @own_delegations ||= {}
end

.own_global_actions ⇒ Object 


77
78
79
 
# File 'lib/declarative_policy/base.rb', line 77

def own_global_actions
  @own_global_actions ||= []
end

.prevent_all_when(rule) ⇒ Object

we store global prevents (from `prevent_all`) separately, so that they can be combined into every decision made.


205
206
207
 
# File 'lib/declarative_policy/base.rb', line 205

def prevent_all_when(rule)
  own_global_actions << [:prevent, rule]
end

.prevent_when(abilities, rule) ⇒ Object 


199
200
201
 
# File 'lib/declarative_policy/base.rb', line 199

def prevent_when(abilities, rule)
  abilities.each { |a| own_ability_map.prevent(a, rule) }
end

.rule(&block) ⇒ Object

Declares a rule, constructed using RuleDsl, and returns a PolicyDsl which is used for registering the rule with this class. PolicyDsl will call back into Base.enable_when, Base.prevent_when, and Base.prevent_all_when.


141
142
143
144
 
# File 'lib/declarative_policy/base.rb', line 141

def rule(&block)
  rule = RuleDsl.new(self).instance_eval(&block)
  PolicyDsl.new(self, rule)
end

.with_options(opts = {}) ⇒ Object 


163
164
165
 
# File 'lib/declarative_policy/base.rb', line 163

def with_options(opts = {})
  last_options.merge!(opts)
end

.with_scope(scope) ⇒ Object 


167
168
169
 
# File 'lib/declarative_policy/base.rb', line 167

def with_scope(scope)
  with_options scope: scope
end

.with_score(score) ⇒ Object 


171
172
173
 
# File 'lib/declarative_policy/base.rb', line 171

def with_score(score)
  with_options score: score
end

Instance Method Details

#allowed?(*abilities) ⇒ Boolean

This is the main entry point for permission checks. It constructs or looks up a Runner for the given ability and asks it if it passes.

Returns:

  • (Boolean) 

233
234
235
 
# File 'lib/declarative_policy/base.rb', line 233

def allowed?(*abilities)
  abilities.all? { |a| runner(a).pass? }
end

#banned? ⇒ Boolean

used in specs - returns true if there is no possible way for any action to be allowed, determined only by the global :prevent_all rules.

Returns:

  • (Boolean) 

325
326
327
328
 
# File 'lib/declarative_policy/base.rb', line 325

def banned?
  global_steps = self.class.global_actions.map { |(action, rule)| Step.new(self, rule, action) }
  !Runner.new(global_steps).pass?
end

#cache(key) ⇒ Object

Helpers for caching. Used by ManifestCondition in performing condition computation.

NOTE we can't use ||= here because the value might be the boolean `false`


300
301
302
303
304
 
# File 'lib/declarative_policy/base.rb', line 300

def cache(key)
  return @cache[key] if cached?(key)

  @cache[key] = yield
end

#cached?(key) ⇒ Boolean

Returns:

  • (Boolean) 

306
307
308
 
# File 'lib/declarative_policy/base.rb', line 306

def cached?(key)
  !@cache[key].nil?
end

#can?(ability, new_subject = :_self) ⇒ Boolean

helper for checking abilities on this and other subjects for the current user.

Returns:

  • (Boolean) 

225
226
227
228
229
 
# File 'lib/declarative_policy/base.rb', line 225

def can?(ability, new_subject = :_self)
  return allowed?(ability) if new_subject == :_self

  policy_for(new_subject).allowed?(ability)
end

#condition(name) ⇒ Object

returns a ManifestCondition capable of computing itself. The computation will use our own @cache.


312
313
314
315
316
317
318
319
320
321
 
# File 'lib/declarative_policy/base.rb', line 312

def condition(name)
  name = name.to_sym
  @_conditions ||= {}
  @_conditions[name] ||=
    begin
      raise "invalid condition #{name}" unless self.class.conditions.key?(name)

      ManifestCondition.new(self.class.conditions[name], self)
    end
end

#debug(ability, *args) ⇒ Object

computes the given ability and prints a helpful debugging output showing which


244
245
246
 
# File 'lib/declarative_policy/base.rb', line 244

def debug(ability, *args)
  runner(ability).debug(*args)
end

#delegated_policies ⇒ Object

A list of other policies that we've delegated to (see `Base.delegate`)


331
332
333
334
335
336
337
338
339
340
 
# File 'lib/declarative_policy/base.rb', line 331

def delegated_policies
  @delegated_policies ||= self.class.delegations.transform_values do |block|
    new_subject = instance_eval(&block)

    # never delegate to nil, as that would immediately prevent_all
    next if new_subject.nil?

    policy_for(new_subject)
  end
end

#disallowed?(*abilities) ⇒ Boolean

The inverse of #allowed?, used mainly in specs.

Returns:

  • (Boolean) 

238
239
240
 
# File 'lib/declarative_policy/base.rb', line 238

def disallowed?(*abilities)
  abilities.all? { |a| !runner(a).pass? }
end

#inspect ⇒ Object 


272
273
274
 
# File 'lib/declarative_policy/base.rb', line 272

def inspect
  "#<#{self.class.name} #{repr}>"
end

#policy_for(other_subject) ⇒ Object 


342
343
344
 
# File 'lib/declarative_policy/base.rb', line 342

def policy_for(other_subject)
  DeclarativePolicy.policy_for(@user, other_subject, cache: @cache)
end

#repr ⇒ Object 


254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/declarative_policy/base.rb', line 254

def repr
  subject_repr =
    if @subject.respond_to?(:id)
      "#{@subject.class.name}/#{@subject.id}"
    else
      @subject.inspect
    end

  user_repr =
    if @user
      @user.to_reference
    else
      "<anonymous>"
    end

  "(#{user_repr} : #{subject_repr})"
end

#runner(ability) ⇒ Object

returns a Runner for the given ability, capable of computing whether the ability is allowed. Runners are cached on the policy (which itself is cached on @cache), and caches its result. This is how we perform caching at the ability level.


280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/declarative_policy/base.rb', line 280

def runner(ability)
  ability = ability.to_sym
  @runners ||= {}
  @runners[ability] ||=
    begin
      own_runner = Runner.new(own_steps(ability))
      if self.class.overrides.include?(ability)
        own_runner
      else
        delegated_runners = delegated_policies.values.compact.map { |p| p.runner(ability) }
        delegated_runners.inject(own_runner, &:merge_runner)
      end
    end
end