Class: Permit::PermitRule

Inherits:
Object
  • Object
show all
Includes:
Support
Defined in:
lib/permit/permit_rule.rb

Overview

Defines an authorization rule to match against.

Constant Summary

VALID_OPTION_KEYS = 
[:who, :that, :of, :on, :if, :unless]
BUILTIN_ROLES = 
[:person, :guest, :everyone]

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Methods included from Support

#authorization_conditions, #get_role, #get_roles, #permit_arrayify, #resource_conditions, #role_condition

Constructor Details

- (PermitRule) initialize(roles, options = {})

Creates a new PermitRule.

:if and :unless conditions may be evaluated for static, dynamic, and named authorizations. They are evaluated after the other rule checks are applied, and only if the rule still matches. The conditionals may make a matching rule not match, but will not make an unmatched rule match. If both :if and :unless are given the :if condition is run first, and if the rule still matches the :unless will be run.

Parameters:

  • roles (:person, :guest, :everyone, Symbol, <Symbol>) —

    the role(s) to test against.

    • :person - current_person.guest? == false This person should be authenticated. This indicates a dynamic authorization.

    • :guest - current_person.guest? == true This is a person that is not authenticated. This is a static authorization.

    • :everyone - Any user of the system. This is a static authorization.

    • Symbol/<Symbol> - This is the key or keys of any of the role(s) to match against in the database. This indicates a named authorization.

  • options (Hash) (defaults to: {}) —

    the options to use to configure the authorization.

Options Hash (options):

  • :who (Symbol) —

    Indicates that a method should be checked on the target object to authorize. Checks a variety of possibilities, taking the first variation that the target responds to.

    When the symbol is prefixed with 'is_' then multiple methods will be tried passing the person in. The methods tried for :is_owner would be is_owner(), is_owner?(), owner(), owner, owners.exist?(). If this option is given :of/:on must also be given.

  • :that (Symbol) —

    alias for :who

  • :of (Symbol, nil, :any, <Symbol, nil>) —

    The name of the instance variable(s) to use as the target resource(s).

    In a dynamic authorization this is the object that will be tested using the value of :who/:that.

    In a named authorization this is the resource the person must be authorized on for one or more of the roles. :any may be given to indicate a match if the person has one of the roles for any resource. If not given, or set to nil, then the match will apply to a person that has a matching role authorization for a nil resource.

  • :on (Symbol, nil, :any, <Symbol, nil>) —

    alias for :of

  • :if (Symbol, String, Proc) —

    code to evaluate at the end of the match if it is still valid. If it returns false, the rule will not match. If a proc if given, it will be passed the current subject and binding. A method will be called without any arguments.

  • :unless (Symbol, String, Proc) —

    code to evaluate at the end of the match if it is still valid. If it returns true, the rule will not match. If a proc if given, it will be passed the current subject and binding. A method will be called without any arguments.

Raises:



61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/permit/permit_rule.rb', line 61

def initialize(roles, options = {})
  options.assert_valid_keys *VALID_OPTION_KEYS

  @roles = validate_roles(roles).freeze

  validate_options options

  @method = options[:who] || options[:that]
  @target_vars = permit_arrayify(options[:of] || options[:on]).uniq.freeze

  @if = options[:if]
  @unless = options[:unless]
end

Instance Attribute Details

- (Object) if (readonly)

Returns the value of attribute if



9
10
11
 
# File 'lib/permit/permit_rule.rb', line 9

def if
  @if
end

- (Object) method (readonly)

Returns the value of attribute method



9
10
11
 
# File 'lib/permit/permit_rule.rb', line 9

def method
  @method
end

- (Object) roles (readonly)

Returns the value of attribute roles



9
10
11
 
# File 'lib/permit/permit_rule.rb', line 9

def roles
  @roles
end

- (Object) target_vars (readonly)

Returns the value of attribute target_vars



9
10
11
 
# File 'lib/permit/permit_rule.rb', line 9

def target_vars
  @target_vars
end

- (Object) unless (readonly)

Returns the value of attribute unless



9
10
11
 
# File 'lib/permit/permit_rule.rb', line 9

def unless
  @unless
end

Instance Method Details

- (Boolean) matches?(person, context_binding)

Determine if the passed in person matches this rule.

Parameters:

  • person (permit_person) —

    the person to evaluate for authorization

  • context_binding (Binding) —

    the binding to use to locate the resource and/or evaluate the if/unless conditions.

Returns:

  • (Boolean) —

    true if the person matches the rule, otherwise false.

Raises:



83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/permit/permit_rule.rb', line 83

def matches?(person, context_binding)
  matched = if BUILTIN_ROLES.include? @roles[0]
    has_builtin_authorization? person, context_binding
  else
    has_named_authorizations? person, context_binding
  end

  passed_conditionals = matched ? passes_conditionals?(person, context_binding) : false
  passed = matched && passed_conditionals
  return passed
end