declarative_policy 1.0.0 → 2.0.1

data/doc/defining-policies.md

@@ -22,9 +22,9 @@ and then evaluating them with `DeclarativePolicy::Base#allowed?`.
 You may wish to define a method to abstract policy evaluation. Something like:
 
 ```ruby
-def allowed?(user, ability, object)
+def allowed?(user, ability, subject)
   opts = { cache: Cache.current_cache } # re-using a cache between checks eliminates duplication of work
-  policy = DeclarativePolicy.policy_for(user, object, opts)
+  policy = DeclarativePolicy.policy_for(user, subject, opts)
   policy.allowed?(ability)
 end
 ```
@@ -41,9 +41,9 @@ want to know if a user can drive a vehicle. We need a `VehiclePolicy`:
 ```ruby
 class VehiclePolicy < DeclarativePolicy::Base
   # conditions go here by convention
-  
+
   # rules go here by convention
-  
+
   # helper methods go last
 end
 ```
@@ -55,14 +55,14 @@ Conditions are facts about the state of the system.
 They have access to two elements of the proposition:
 
 - `@user` - the representation of a user in your system: the *subject* of the proposition.
-  `user` in `allowed?(user, ability, object)`. `@user` may be `nil`, which means
+  `user` in `allowed?(user, ability, subject)`. `@user` may be `nil`, which means
   that the current user is anonymous (for example this may reflect an
   unauthenticated request in your system).
 - `@subject` - any domain object that has an associated policy: the *object* of
-  the predicate of the proposition. `object` in `allowed?(user, ability, object)`.
+  the predicate of the proposition. `subject` in `allowed?(user, ability, subject)`.
   `@subject` is never `nil`. See [handling `nil` values](./configuration.md#handling-nil-values)
   for details of how to apply policies to `nil` values.
-  
+
 
 They are defined as `condition(name, **options, &block)`, where the block is
 evaluated in the context of an instance of the policy.
@@ -74,7 +74,7 @@ condition(:owns) { @subject.owner == @user }
 condition(:has_access_to) { @subject.owner.trusts?(@user) }
 condition(:old_enough_to_drive) { @user.age >= laws.minimum_age }
 condition(:has_driving_license) { @user.driving_license&.valid? }
-condition(:intoxicated, score: 5) { @user.blood_alcohol < laws.max_blood_alcohol }
+condition(:intoxicated, score: 5) { @user.blood_alcohol > laws.max_blood_alcohol }
 condition(:has_access_to, score: 3) { @subject.owner.trusts?(@user) }
 ```
 
@@ -108,8 +108,7 @@ Rules are conclusions we can draw based on the facts:
 rule { owns }.enable :drive_vehicle
 rule { has_access_to }.enable :drive_vehicle
 rule { ~old_enough_to_drive }.prevent :drive_vehicle
-rule { intoxicated }.prevent :drive_vehicle
-rule { ~has_driving_license }.prevent :drive_vehicle
+rule { intoxicated | ~has_driving_license }.prevent :drive_vehicle
 ```
 
 Rules are combined such that each ability must be enabled at least once, and not
@@ -130,6 +129,33 @@ access the `@user` or `@subject`, or any methods on the policy instance. You
 should not perform I/O in a rule. They exist solely to define the logical rules
 of implication and combination between conditions.
 
+The available operations inside a rule block are:
+
+- Bare words to refer to conditions in the policy, or on any delegate.
+  For example `owns`. This is equivalent to `cond(:owns)`, but as a matter of
+  general style, bare words are preferred.
+- `~` to negate any rule. For example `~owns`, or `~(intoxicated | banned)`.
+- `&` or `all?` to combine rules such that all must succeed. For example:
+  `old_enough_to_drive & has_driving_license` or `all?(old_enough_to_drive, has_driving_license)`.
+- `|` or `any?` to combine rules such that one must succeed. For example:
+  `intoxicated | banned` or `any?(intoxicated, banned)`.
+- `can?` to refer to the result of evaluating an ability. For example,
+  `can?(:sell_vehicle)`.
+- `delegate(:delegate_name, :condition_name)` to refer to a specific
+  condition on a named delegate. Use of this is rare, but can be used to
+  handle overrides. For example if a vehicle policy defines a delegate as
+  `delegate :registration`, then we could refer to that
+  as `rule { delegate(:registration, :valid) }`.
+
+Note: Be careful not to confuse `DeclarativePolicy::Base.condition` with
+`DeclarativePolicy::RuleDSL#cond`.
+
+- `condition` constructs a condition from a name and a block. For example:
+  `condition(:adult) { @subject.age >= country.age_of_majority }`.
+- `cond` constructs a rule which refers to a condition by name. For example:
+  `rule { cond(:adult) }.enable :vote`. Use of `cond` is rare - it is nicer to
+  use the bare word form: `rule { adult }.enable :vote`.
+
 ### Complex conditions
 
 Conditions may be combined in the rule blocks:
@@ -158,7 +184,7 @@ like:
 ```ruby
 class DrivingLicensePolicy < DeclarativePolicy::Base
   condition(:expired) { @subject.expires_at <= Time.current }
-  
+
   rule { expired }.prevent :drive_vehicle
 end
 ```
@@ -168,7 +194,7 @@ And a registration policy:
 ```ruby
 class RegistrationPolicy < DeclarativePolicy::Base
   condition(:valid) { @subject.valid_for?(@user.current_location) }
-  
+
   rule { ~valid }.prevent :drive_vehicle
 end
 ```
@@ -183,3 +209,41 @@ delegate { @subject.registration }
 
 This is a powerful mechanism for inferring rules based on relationships between
 objects.
+
+#### Overrides
+
+It can be useful to declare that the given abilities should not be read
+from delegates. This declaration is useful if you have an ability you want
+to define differently in a policy than in a delegated policy, but you still
+want to delegate all other abilities.
+
+```ruby
+delegate { @subject.parent }
+
+overrides :drive_car, :watch_tv
+```
+
+NOTE:
+Rules with `prevent_all` present in the delegated policy are properly
+not used during overridden abilities evaluation.
+
+#### Delegated conditions
+
+When named delegates are defined, their [conditions](#conditions) can be
+referenced in [rules](#rules) using bare words.
+
+Given a registration policy:
+
+```ruby
+class RegistrationPolicy < DeclarativePolicy::Base
+  condition(:valid) { @subject.valid_for?(@user.current_location) }
+end
+```
+
+The vehicle policy can reference the `:valid` condition as follows:
+
+```ruby
+delegate(:registration) { @subject.registration }
+
+rule { registration.valid }.enable :drive_vehicle
+```

data/doc/optimization.md

@@ -0,0 +1,277 @@
+# Optimization
+
+This library cares a lot about performance, and includes features that
+aim to limit the impact of permission checks on an application. In particular,
+effort is made to ensure that repeated checks of the same permission are
+efficient, aiming to eliminate repeated computation and unnecessary I/O.
+
+The key observation: permission checks generally involve some facts
+about the real world, and this involves (relatively expensive) I/O to compute.
+These facts are then combined in some way to generate a judgment. Not all facts
+are necessary to know in order to determine a judgment. The main aims of the
+library:
+
+- Avoid unnecessary work.
+- If we must do work, do the least work possible.
+
+The library enables you to define both how to compute these facts
+(conditions), and how to combine them (rules), but the library is entirely
+responsible for the scheduling of when to compute each fact.
+
+## Making truth
+
+This library is essentially a build-system for truth - you can think of it as
+similar to [`make`](https://www.gnu.org/software/make/), but:
+
+- Instead of `targets` there are `abilities`.
+- Instead of `files`, we produce `boolean` values.
+
+We have no notion of freshness - uncached conditions are always re-computed, but
+just like `make`, we try to do the least work possible in order to evaluate the
+given ability.
+
+For the interested, this corresponds to
+[`memo`](https://hackage.haskell.org/package/build-1.0/docs/src/Build.System.html#memo) in
+the taxonomy of build systems (although the scheduler here is somewhat smarter
+about the relative order of dependencies).
+
+## Optimization is reducing computation of expensive I/O
+
+In the context of this library, optimization refers to ways we can:
+
+- Expose the smallest possible units of I/O to the scheduler.
+- Never run a computation twice.
+- Indicate to the scheduler which computations should be run first.
+
+For example, if a policy defines the following rule:
+
+```ruby
+rule { fact_a & fact_b }.enable :some_ability
+```
+
+The core of the matter: if we know in advance that `fact_a == false`, then we do not need to compute
+`fact_b`. Conversely, if we know in advance that `fact_b == false`, then we do
+not need to run `fact_a`. The same goes for `fact_a | fact_a`.
+
+In this case:
+
+- The smallest possible units of I/O are `fact_a` and `fact_b`, and the library
+  is aware of them.
+- The library uses the [cache](./caching.md) to avoid running a condition more
+  than once.
+- It does not matter which order we run these conditions in - the scheduler is
+  free to re-order them if it thinks that `fact_b` is somehow more efficient to
+  compute than `fact_a`.
+
+## The scheduling logic
+
+The problem each permission check seeks to solve is determining the truth value
+of a proposition of the form:
+
+```pseudo
+any? enabling-conditions && not (any? preventing-conditions)
+```
+
+If `[a, b, c]` are enabling conditions, and `[x, y, z]` are preventing
+conditions, then this could be expressed as:
+
+```ruby
+(a | b | c) & ~x & ~y & ~z
+```
+
+But the [scheduler](../lib/declarative_policy/runner.rb) represents this
+as a flat list of rules - conditions and their outcomes:
+
+```pseudo
+[
+  (a, :enable),
+  (b, :enable),
+  (c, :enable),
+  (x, :prevent),
+  (y, :prevent),
+  (z, :prevent)
+]
+```
+
+They aren't necessarily run in this order, however. Instead, we try to order
+the list to minimize unnecessary work.
+
+The
+[logic](https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/blob/659ac0525773a76cf8712d47b3c2dadd03b758c9/lib/declarative_policy/runner.rb#L80-112)
+to process this list is (in pseudo-code):
+
+```pseudo
+while any-enable-rule-remains?(rules)
+  rule := pop-cheapest-remaining-rule(rules)
+  fact := observe-io-and-update-cache rule.condition
+
+  if fact and rule.prevents?
+    return prevented
+  else if fact and rule.enables?
+    skip-all-other-enabling-rules!
+    enabled? := true
+
+if enabled?
+  return enabled
+else
+  return prevented
+```
+
+The process for ordering rules is that each condition has a score, and we prefer
+the rules with the lowest `score`. Cached values have a score of `0`. Composite
+conditions (such as `a | b | c`) have a score that the sum of the scores of
+their components.
+
+The evaluation of one rule results in updating the cache, so other rules might
+become cheaper, during policy evaluation. To take this into account, we re-score
+the set of rules on each iteration of the main loop.
+
+## Consequences for the policy-writer
+
+While interesting in its own right, this has some practical consequences for the
+policy writer:
+
+### Flat is better than nested
+
+The scheduler can do a better job of arranging work into the smallest possible
+chunks if the definitions are as flat as possible, meaning this:
+
+```ruby
+rule { condition_a }.enable :some_ability
+rule { condition_b }.prevent :some_ability
+```
+
+Is easier to optimise than:
+
+```ruby
+rule { condition_a & ~condition_b }.enable :some_ability
+```
+
+We do attempt to flatten and de-nest logical expressions, but it is not always
+possible to raise all expressions to the top level. All things being
+equal, we recommend using the declarative style.
+
+#### An example of sub-optimal scheduling
+
+The scheduler is only able to re-order conditions that can be flattened out to
+the top level. For example, given the following definition:
+
+```ruby
+condition(:a, score: 1) { ... }
+condition(:b, score: 2) { ... }
+condition(:c, score: 3) { ... }
+
+rule { a & c }.enable :some_ability
+rule { b & c }.enable :some_ability
+```
+
+The conditions are evaluated in the following order:
+
+- `a & c` (score = 4):
+  - `a` (score = 1)
+  - `c` (score = 3)
+- `b & c` (score = 3):
+  - `c` (score = 0 [cached])
+  - `b` (score = 2)
+
+If instead this were three top level rules:
+
+```ruby
+rule { a }.enable :some_ability
+rule { b }.enable :some_ability
+rule { ~c }.prevent :some_ability
+```
+
+Then this would be evaluated as:
+
+- `a` (score = 1)
+- `b` (score = 2)
+- `c` (score = 3)
+
+If `a` and `b` fail, then `3` is never evaluated, saving the most
+expensive call.
+
+The total evaluated costs for each arrangement are:
+
+| Failing conditions | Nested cost     | Flat cost     |
+|--------------------|-----------------|---------------|
+| none               | 4 `(a, c)`      | 4 `(a, c)`    |
+| all                | 3 `(a, b)`      | 3 `(a, b)`    |
+| `a`                | 6 `(a, b, c)`   | 6 `(a, b, c)` |
+| `b`                | 4 `(a, c)`      | 4 `(a, c)`    |
+| `c`                | 4 `(a, c, c=0)` | 4 `(a, c)`    |
+| `a` and `b`        | 4 `(a, c, c=0)` | 3 `(a, b)`    |
+| `a` and `c`        | 6 `(a, b, c)`   | 6 `(a, b, c)` |
+| `b` and `c`        | 4 `(a, c, c=0)` | 4 `(a, c)`    |
+
+While the overall costs for all arrangements are very similar,
+the flat representation is strictly superior, and does not even need to
+rely on the cache for this behavior.
+
+### Getting the scope right matters
+
+By default, the outcome of each rule is cached against a key like
+`(rule.condition.key, user.key, subject.key)`. (For more information, read
+[caching](./caching.md).) This makes sense for some things like:
+
+```ruby
+condition(:owns_vehicle) { @user == @subject.owner }
+```
+
+In this case, the result depends on both the `@user` and the `@subject`. Not all
+conditions are like that, though! The following condition only refers to the
+subject:
+
+```ruby
+condition(:roadworthy) { @subject.warrant_of_fitness.current? }
+```
+
+If we cached this against `(user_a, car_a)` and then tested it
+against `(user_b, car_a)` it would not match, and we would have to re-compute
+the condition, even though the road-worthiness of a vehicle does not depend on
+the driver. See [caching](./caching.md) for more discussion on scopes.
+
+Because more general conditions are more sharable, all things being equal, it is
+better to evaluate a condition that might be shared later, rather than one that
+is less likely to be shared. For this reason, when we sort the rules,
+we prefer ones with more general scopes to more specific ones.
+
+### Getting the score right matters
+
+Each condition has a `score`, which is an abstract weight. By default this is
+determined by the scope.
+
+However, if you know that a condition is very expensive to run, then it makes sense
+to give it a higher score, meaning it's only evaluated if we really need
+to. On the other hand, if a condition is very likely to be determinative, then
+giving it a lower score would ensure we test it first.
+
+For example, take two conditions, one which queries the local DB, and one
+which makes an external API call. If they are otherwise equivalent, calling
+the database one first is likely to be more efficient, as it might save us needing
+to make the external API call. Conditions that are
+[pure](https://en.wikipedia.org/wiki/Pure_function) can even be given a value of
+`0`, as no I/O is required to compute them.
+
+```ruby
+condition(:local_db) { @subject.related_object.present? }
+condition(:pure, score: 0) { @subject.some_attribute? }
+condition(:external_api, score: API_SCORE) { ExtrnalService.get(@subject.id).ok? }
+
+# these are run in the order: pure, local_db, external_api
+rule { external_api & pure & local_db }.enable :some_ability
+```
+
+The other consideration is the likelihood that a condition is determinative. For
+example, if `condition_a` is true 80% of the time, and `condition_b` is true
+20% of the time, then we should prefer to run `condition_a` if these conditions
+enable an ability (because 80% of the time we don't need to run `condition_b`).
+But if they prevent an ability, then we would prefer to run `condition_b` first,
+because again, 80% of the time we can skip `condition_a`. This consideration is
+more subtle. It requires knowing both the distribution of the condition, and
+the consequence of its outcome, but this can be used to further optimize the
+order of evaluation by marking some conditions as more likely to affect the
+outcome.
+
+All things being equal, we prefer to run prevent rules, because they have this
+property - they are more likely to save extra work.

data/lib/declarative_policy/base.rb

@@ -33,6 +33,24 @@ module DeclarativePolicy
       end
     end
 
+    class Options
+      def initialize
+        @hash = {}
+      end
+
+      def []=(key, value)
+        @hash[key.to_sym] = value
+      end
+
+      def [](key)
+        @hash[key.to_sym]
+      end
+
+      def to_h
+        @hash
+      end
+    end
+
     class << self
       # The `own_ability_map` vs `ability_map` distinction is used so that
       # the data structure is properly inherited - with subclasses recursively
@@ -126,7 +144,7 @@ module DeclarativePolicy
       #
       # example:
       #
-      #   delegate { @subect.parent }
+      #   delegate { @subject.parent }
       #
       #   overrides :drive_car, :watch_tv
       #
@@ -146,46 +164,40 @@ module DeclarativePolicy
 
       # A hash in which to store calls to `desc` and `with_scope`, etc.
       def last_options
-        @last_options ||= {}.with_indifferent_access
+        @last_options ||= Options.new
       end
 
-      # retrieve and zero out the previously set options (used in .condition)
-      def last_options!
-        last_options.tap { @last_options = nil }
+      def with_options(opts = {})
+        last_options.to_h.merge!(opts.to_h)
       end
 
       # 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.
       def desc(description)
-        last_options[:description] = description
-      end
-
-      def with_options(opts = {})
-        last_options.merge!(opts)
+        with_options description: description
       end
 
+      # Declare a scope for the following condition.
       def with_scope(scope)
         with_options scope: scope
       end
 
+      # Declare a score for the following condition.
       def with_score(score)
         with_options score: score
       end
 
       # Declares a condition. It gets stored in `own_conditions`, and generates
       # a query method based on the condition's name.
-      def condition(name, opts = {}, &value)
-        name = name.to_sym
+      def condition(condition_name, opts = {}, &value)
+        condition_name = condition_name.to_sym
 
-        opts = last_options!.merge(opts)
-        opts[:context_key] ||= self.name
+        condition = Condition.new(condition_name, condition_options(opts), &value)
 
-        condition = Condition.new(name, opts, &value)
+        own_conditions[condition_name] = condition
 
-        own_conditions[name] = condition
-
-        define_method(:"#{name}?") { condition(name).pass? }
+        define_method(:"#{condition_name}?") { condition(condition_name).pass? }
       end
 
       # These next three methods are mainly called from PolicyDsl,
@@ -206,6 +218,16 @@ module DeclarativePolicy
       def prevent_all_when(rule)
         own_global_actions << [:prevent, rule]
       end
+
+      private
+
+      # retrieve and zero out the previously set options (used in .condition)
+      def condition_options(opts)
+        # The context_key distinguishes two conditions of the same name.
+        # For anonymous classes, use object_id.
+        opts[:context_key] ||= (name || object_id)
+        with_options(opts).tap { @last_options = nil }
+      end
     end
 
     # A policy object contains a specific user and subject on which
@@ -254,16 +276,23 @@ module DeclarativePolicy
     condition(:default, scope: :global, score: 0) { true }
 
     def repr
-      subject_repr =
-        if @subject.respond_to?(:id)
-          "#{@subject.class.name}/#{@subject.id}"
-        else
-          @subject.inspect
-        end
+      "(#{identify_user} : #{identify_subject})"
+    end
 
-      user_repr = @user.try(:to_reference) || '<anonymous>'
+    def identify_user
+      return '<anonymous>' unless @user
 
-      "(#{user_repr} : #{subject_repr})"
+      @user.to_reference
+    rescue NoMethodError
+      "<#{@user.class}: #{@user.object_id}>"
+    end
+
+    def identify_subject
+      if @subject.respond_to?(:id)
+        "#{@subject.class.name}/#{@subject.id}"
+      else
+        @subject.inspect
+      end
     end
 
     def inspect
@@ -276,19 +305,22 @@ module DeclarativePolicy
     # at the ability level.
     def runner(ability)
       ability = ability.to_sym
-      @runners ||= {}
-      @runners[ability] ||=
+      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)
+            delegated_runners.reduce(own_runner, &:merge_runner)
           end
         end
     end
 
+    def runners
+      @runners ||= {}
+    end
+
     # Helpers for caching. Used by ManifestCondition in performing condition
     # computation.
     #

data/lib/declarative_policy/cache.rb

@@ -6,7 +6,7 @@ module DeclarativePolicy
       def user_key(user)
         return '<anonymous>' if user.nil?
 
-        id_for(user)
+        "#{user.class.name}:#{id_for(user)}"
       end
 
       def policy_key(user, subject)

data/lib/declarative_policy/condition.rb

@@ -9,10 +9,14 @@ module DeclarativePolicy
   class Condition
     attr_reader :name, :description, :scope, :manual_score, :context_key
 
+    VALID_SCOPES = %i[user_and_subject user subject global].freeze
+    ALLOWED_SCOPES = VALID_SCOPES + %i[normal]
+
     def initialize(name, opts = {}, &compute)
       @name = name
       @compute = compute
-      @scope = opts.fetch(:scope, :normal)
+      @scope = fetch_scope(opts)
+
       @description = opts.delete(:description)
       @context_key = opts[:context_key]
       @manual_score = opts.fetch(:score, nil)
@@ -25,6 +29,20 @@ module DeclarativePolicy
     def key
       "#{@context_key}/#{@name}"
     end
+
+    private
+
+    def fetch_scope(options)
+      result = options.fetch(:scope, :user_and_subject)
+      if result == :normal
+        warn "[DEPRECATION] `:normal` is deprecated and will be removed in 2.0. Please use new name `:user_and_subject`"
+        result = :user_and_subject
+      end
+
+      raise "Invalid scope #{result}. Allowed values: #{VALID_SCOPES.inspect}" unless ALLOWED_SCOPES.include?(result)
+
+      result
+    end
   end
 
   # In contrast to a Condition, a ManifestCondition contains
@@ -40,6 +58,8 @@ module DeclarativePolicy
     # the context's cache here so that we can share in the global
     # cache (often RequestStore or similar).
     def pass?
+      Thread.current[:declarative_policy_current_runner_state]&.register(self)
+
       @context.cache(cache_key) { @condition.compute(@context) }
     end
 
@@ -66,7 +86,7 @@ module DeclarativePolicy
       return 2 if  @condition.scope == :global
 
       # "Normal" rules can't share caches with any other policies
-      return 16 if @condition.scope == :normal
+      return 16 if @condition.scope == :user_and_subject
 
       # otherwise, we're :user or :subject scope, so it's 4 if
       # the caller has declared a preference
@@ -76,8 +96,6 @@ module DeclarativePolicy
       8
     end
 
-    private
-
     # This method controls the caching for the condition. This is where
     # the condition(scope: ...) option comes into play. Notice that
     # depending on the scope, we may cache only by the user or only by
@@ -85,14 +103,15 @@ module DeclarativePolicy
     def cache_key
       @cache_key ||=
         case @condition.scope
-        when :normal  then "/dp/condition/#{@condition.key}/#{user_key},#{subject_key}"
+        when :global  then "/dp/condition/#{@condition.key}"
         when :user    then "/dp/condition/#{@condition.key}/#{user_key}"
         when :subject then "/dp/condition/#{@condition.key}/#{subject_key}"
-        when :global  then "/dp/condition/#{@condition.key}"
-        else raise 'invalid scope'
+        else "/dp/condition/#{@condition.key}/#{user_key},#{subject_key}"
         end
     end
 
+    private
+
     def user_key
       Cache.user_key(@context.user)
     end