declarative_policy 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 735e59059f970e9e39c6fc37b1d97f7b20c030a472ca287cb95d4503a168c3a3
-  data.tar.gz: e4bd527d1ab32d86a77666e9b0c175a2e5c1cc8d4627b94fa3d01eb8c6dc6e10
+  metadata.gz: bf0b45880663f66032b9313af36819d078739f7430b53c9f182a4a8904acb443
+  data.tar.gz: c4e162b87f85d1008d5fa956f72f4745c4bb208b59796f95b472f4606504f295
 SHA512:
-  metadata.gz: 65796bc8d62ce7648433adba6feb99e78e2fff32c27902318a8394973fad38a8b7a476b8a13806178c8d4b20f8f5385e398336c2872a6c58122d213c8d864fbb
-  data.tar.gz: 4ab6e8f55e9efadbf2169bd4b385ec8620fdca8247cfcc1b977fc3ac5fb02f045fb1616caef9878fd0e92f37f6a98c0a58b04f458c9b2c67aec98d4b22545b99
+  metadata.gz: 41f679b05618e46bfc952406e211ddbe8512a25b86c254f6c0793d1293a67689414149765ca2e12e1368462669d06685c4af603307661a674d1999475fa2e1e9
+  data.tar.gz: ab068e42451bf95c939eb5952fbb8319741927d123faedd1d2f9713323cee26e019632d053cef1eddc4fc88d937501c062f80ba982e3d183d5ff9bac60cdae81

data/doc/caching.md

@@ -148,9 +148,16 @@ The object only needs to implement the following methods:
 Obviously, a `HashMap` will work just fine, but so will a wrapper around a
 [`Concurrent::Map`](https://ruby-concurrency.github.io/concurrent-ruby/1.1.4/Concurrent/Map.html),
 or even a map that delegates to Redis with a TTL for each key, so long as the
-object supports these methods. Keys are never deleted by the library, and values
-are only computed if the key is not cached, so it is up to the application code
-to determine the life-time of each key.
+object supports these methods. Values are only computed if the key is not
+cached, so it is up to the application code to determine the life-time of each
+key.
+
+To remove keys, use `DeclarativePolicy.invalidate(cache, keys)`. It also makes
+the abilities that depended on those keys check again, and tells the library
+that scores used to order checks may have changed. Keys removed in any other
+way, such as by a TTL expiring, don't change a decision a policy has already
+made, and may make checks run in a less efficient order until the library
+next sees a change.
 
 Clearly, cache-invalidation is a hard problem. At GitLab we share a single cache
 object for each request - so any single request can freely request a permission

data/doc/optimization.md

@@ -124,7 +124,9 @@ 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.
+the set of rules on each iteration of the main loop. Each rule keeps its score
+until something it depends on changes, such as a condition being cached, so
+re-scoring is cheap.
 
 ## Consequences for the policy-writer
 

data/lib/declarative_policy/base.rb

@@ -399,7 +399,11 @@ module DeclarativePolicy
     def cache(key)
       return @cache[key] if cached?(key)
 
-      @cache[key] = yield
+      # Advance the score epoch only once the value is stored: checks run by
+      # the block would otherwise keep scores that see the key as missing.
+      value = @cache[key] = yield
+      DeclarativePolicy.advance_score_epoch!
+      value
     end
 
     def cached?(key)

data/lib/declarative_policy/preferred_scope.rb

@@ -4,12 +4,16 @@ module DeclarativePolicy
   module PreferredScope
     PREFERRED_SCOPE_KEY = :'DeclarativePolicy.preferred_scope'
 
+    # Scores depend on the preferred scope (see ManifestCondition#score), so
+    # changing it advances the score epoch. The scope is per fiber but the
+    # epoch is not, so fibers sharing a cache with different scopes may see
+    # each other's scores. That can only change the order of checks.
     def with_preferred_scope(scope)
       old_scope = Thread.current[PREFERRED_SCOPE_KEY]
-      Thread.current[PREFERRED_SCOPE_KEY] = scope
+      self.preferred_scope = scope
       yield
     ensure
-      Thread.current[PREFERRED_SCOPE_KEY] = old_scope
+      self.preferred_scope = old_scope
     end
 
     def preferred_scope
@@ -25,7 +29,10 @@ module DeclarativePolicy
     end
 
     def preferred_scope=(scope)
+      return if Thread.current[PREFERRED_SCOPE_KEY] == scope
+
       Thread.current[PREFERRED_SCOPE_KEY] = scope
+      DeclarativePolicy.advance_score_epoch!
     end
   end
 end

data/lib/declarative_policy/runner.rb

@@ -66,6 +66,8 @@ module DeclarativePolicy
     def initialize(steps)
       @steps = steps
       @state = nil
+      @score = nil
+      @score_epoch = nil
     end
 
     # We make sure only to run any given Runner once,
@@ -78,13 +80,20 @@ module DeclarativePolicy
     # Delete the cached state - allowing this runner to be re-used if the facts have changed.
     def uncache!
       @state = nil
+      DeclarativePolicy.advance_score_epoch!
     end
 
-    # used by Rule::Ability. See #steps_by_score
+    # used by Rule::Ability. See #steps_by_score, and Step#score for how
+    # scores are kept.
     def score
       return 0 if cached?
 
-      steps.sum(&:score)
+      epoch = DeclarativePolicy.score_epoch
+      return @score if @score_epoch == epoch
+
+      @score = compute_score
+      @score_epoch = epoch
+      @score
     end
 
     def merge_runner(other)
@@ -115,19 +124,66 @@ module DeclarativePolicy
 
     private
 
+    # A run that raises part way through leaves no state behind, so the next
+    # check runs again rather than reading a half-finished decision.
+    #
+    # A runner counts as cached from the start of its run, which changes the
+    # score of every step that depends on it, so the score epoch advances
+    # when the run starts, and again when a failed run is discarded.
     def with_state
       @state = State.new
+      DeclarativePolicy.advance_score_epoch!
       old_runner_state = Thread.current[:declarative_policy_current_runner_state]
       Thread.current[:declarative_policy_current_runner_state] = @state
+      finished = false
 
       yield
+      finished = true
     ensure
       Thread.current[:declarative_policy_current_runner_state] = old_runner_state
+      uncache! unless finished
+    end
+
+    def compute_score
+      steps.sum(&:score)
     end
 
     def flatten_steps!
-      @steps = @steps.flat_map { |s| s.flattened(@steps) }
+      roots = @steps.size > RootSteps::MAX_SCANNED_STEPS ? RootSteps.new(@steps) : @steps
+      @steps = @steps.flat_map { |s| s.flattened(roots) }
+    end
+
+    # The steps being flattened, for Step#flattened to tell whether a step is
+    # among them. A faster stand-in for Array#include?, which compares every
+    # step with Step#==. Rules and policies don't define ==, so comparing
+    # them by identity gives the same answer. The index is built on first
+    # use, since only `can?` rules need it.
+    class RootSteps
+      # Up to this many steps, scanning the array is cheaper than building
+      # the index.
+      MAX_SCANNED_STEPS = 8
+
+      def initialize(steps)
+        @steps = steps
+        @index = nil
+      end
+
+      def include?(step)
+        actions = index[step.rule]&.[](step.context)
+
+        actions ? actions.include?(step.action) : false
+      end
+
+      private
+
+      def index
+        @index ||= @steps.each_with_object({}.compare_by_identity) do |step, by_rule|
+          by_context = (by_rule[step.rule] ||= {}.compare_by_identity)
+          (by_context[step.context] ||= []) << step.action
+        end
+      end
     end
+    private_constant :RootSteps
 
     # This method implements the semantic of "one enable and no prevents".
     # It relies on #steps_by_score for the main loop, and updates @state
@@ -180,7 +236,7 @@ module DeclarativePolicy
     # So! The way we sort here involves re-scoring at every step. This
     # is by necessity quadratic, but most of the time the number of steps
     # will be low. But just in case, if the number of steps exceeds 50,
-    # we print a warning and fall back to a static sort.
+    # we fall back to a static sort.
     #
     # For each step, we yield the step object along with the computed score
     # for debugging purposes.
@@ -188,8 +244,6 @@ module DeclarativePolicy
       flatten_steps!
 
       if @steps.size > 50
-        warn "DeclarativePolicy: large number of steps (#{steps.size}), falling back to static sort"
-
         @steps.map { |s| [s.score, s] }.sort_by { |(score, _)| score }.each do |(score, step)|
           yield step, score
         end

data/lib/declarative_policy/step.rb

@@ -13,6 +13,8 @@ module DeclarativePolicy
       @context = context
       @rule = rule
       @action = action
+      @score = nil
+      @score_epoch = nil
     end
 
     # In the flattening process, duplicate steps may be generated in the
@@ -26,15 +28,17 @@ module DeclarativePolicy
     # we are sure to compute them in close to the optimal order.
     #
     # See also Rule#score, ManifestCondition#score, and Runner#steps_by_score.
+    #
+    # A score only changes when the score epoch does, so it is kept until
+    # then. The epoch is read before scoring, since scoring can run code that
+    # advances it.
     def score
-      # we slightly prefer the preventative actions
-      # since they are more likely to short-circuit
-      case @action
-      when :prevent
-        @rule.score(@context) * (7.0 / 8)
-      when :enable
-        @rule.score(@context)
-      end
+      epoch = DeclarativePolicy.score_epoch
+      return @score if @score_epoch == epoch
+
+      @score = compute_score
+      @score_epoch = epoch
+      @score
     end
 
     def with_action(action)
@@ -61,7 +65,19 @@ module DeclarativePolicy
         # in some cases. If we depend on an Ability (i.e. a `can?(...)` rule),
         # and that ability *only* has :enable actions (modulo some actions that
         # we already have taken care of), then its rules can be safely inlined.
-        steps = @context.runner(@rule.ability).steps.reject { |s| roots.include?(s) }
+        #
+        # Steps that are already in `roots` are skipped, since they run anyway.
+        # A :prevent step can only skip :prevent steps, because each :enable
+        # step it inlines would turn into a :prevent. For example, with
+        #
+        #   rule { member }.enable :read, :write
+        #   rule { can?(:read) }.prevent :write
+        #
+        # `enable when member` is already a step of :write, but inlining needs
+        # `prevent when member`, so it must not be skipped.
+        steps = @context.runner(@rule.ability).steps.reject do |s|
+          roots.include?(s) && !(prevent? && s.enable?)
+        end
 
         if steps.all?(&:enable?)
           # in the case that we are a :prevent step, each inlined step becomes
@@ -85,5 +101,18 @@ module DeclarativePolicy
     def repr
       "#{@action} when #{@rule.repr} (#{@context.repr})"
     end
+
+    private
+
+    def compute_score
+      # we slightly prefer the preventative actions
+      # since they are more likely to short-circuit
+      case @action
+      when :prevent
+        @rule.score(@context) * (7.0 / 8)
+      when :enable
+        @rule.score(@context)
+      end
+    end
   end
 end

data/lib/declarative_policy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeclarativePolicy
-  VERSION = '2.2.0'
+  VERSION = '2.3.0'
 end

data/lib/declarative_policy.rb

@@ -19,7 +19,23 @@ require_relative 'declarative_policy/configuration'
 module DeclarativePolicy
   extend PreferredScope
 
+  # Counts changes to anything a step's score depends on: a condition being
+  # cached, a runner starting or being uncached, and the preferred scope.
+  # Steps and runners keep their last score until this changes (see
+  # Step#score). It is shared by every thread. A change made elsewhere, or an
+  # update lost on a Ruby without a global lock, can only change the order of
+  # checks, not their result.
+  @score_epoch = 0
+
   class << self
+    # @api private
+    attr_reader :score_epoch
+
+    # @api private
+    def advance_score_epoch!
+      @score_epoch += 1
+    end
+
     def policy_for(user, subject, opts = {})
       cache = opts[:cache] || {}
       key = Cache.policy_key(user, subject)
@@ -43,6 +59,7 @@ module DeclarativePolicy
       end
 
       invalidated_keys.each { |k| cache.delete(k) }
+      advance_score_epoch!
 
       nil
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: declarative_policy
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - group::authorization
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-26 00:00:00.000000000 Z
+date: 2026-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips