declarative_policy 2.0.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 704af6c0500c00a0e6c6797dd5b496c098db86f33ccc1ef2496be37e43b33e03
-  data.tar.gz: 2236adb02dbee28b6565fc72541fe2fbee5a087ef15cc2fe1f0d060ce1eece13
+  metadata.gz: 735e59059f970e9e39c6fc37b1d97f7b20c030a472ca287cb95d4503a168c3a3
+  data.tar.gz: e4bd527d1ab32d86a77666e9b0c175a2e5c1cc8d4627b94fa3d01eb8c6dc6e10
 SHA512:
-  metadata.gz: c3841495e1922ae72f704524e40ca080da4838cfe075d401350212f5b31f116f6003aa3e371d2a0084a11986b4745bb82946ad84b61247a19b59470a26e24755
-  data.tar.gz: f3f0d97ba2b9e56079d5307c135ec2b15c73759661f32e6cda2db44ab0fa21002598725cf0c762ca85c0580ae1c5b7c397115f185ec94c9da600cfaf19f6e590
+  metadata.gz: 65796bc8d62ce7648433adba6feb99e78e2fff32c27902318a8394973fad38a8b7a476b8a13806178c8d4b20f8f5385e398336c2872a6c58122d213c8d864fbb
+  data.tar.gz: 4ab6e8f55e9efadbf2169bd4b385ec8620fdca8247cfcc1b977fc3ac5fb02f045fb1616caef9878fd0e92f37f6a98c0a58b04f458c9b2c67aec98d4b22545b99

data/CHANGELOG.md

@@ -1,3 +1,5 @@
+Starting from version 2.0, changelog entries are tracked via https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/-/releases
+
 2.0.0:
 
 - Drop explicit support for Ruby 2.6 and 2.7 by removing those versions from

data/README.md

@@ -202,6 +202,20 @@ https://gitlab.com/gitlab-org/ruby/gems/declarative-policy. This project is inte
 a safe, welcoming space for collaboration, and contributors are expected to
 adhere to the [GitLab code of conduct](https://about.gitlab.com/community/contribute/code-of-conduct/).
 
+## Release process
+
+We release `declarative_policy` on an ad-hoc basis. There is no regularity to when
+we release, we just release when we make a change - no matter the size of the
+change.
+
+To release a new version:
+
+1. Create a Merge Request.
+1. Use Merge Request template [Release.md](https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/-/blob/main/.gitlab/merge_request_templates/Release.md).
+1. Follow the instructions.
+1. After the Merge Request has been merged, a new gem version is [published automatically](https://gitlab.com/gitlab-org/components/gem-release).
+1. Once the new gem version is visible on [RubyGems.org](https://rubygems.org/gems/declarative_policy), it is recommended to update [GitLab's `Gemfile`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/Gemfile) to bump the `declarative_policy` Ruby gem to the new version also.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
@@ -210,4 +224,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 Everyone interacting in the `DeclarativePolicy` project's codebase, issue
 trackers, chat rooms and mailing lists is expected to follow
-the [code of conduct](https://github.com/[USERNAME]/declarative-policy/blob/master/CODE_OF_CONDUCT.md).
+the [code of conduct](https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/blob/main/CODE_OF_CONDUCT.md).

data/declarative-policy.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = 'https://gitlab.com/gitlab-org/ruby/gems/declarative-policy'
-  spec.metadata['changelog_uri'] = 'https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/-/blob/main/CHANGELOG.md'
+  spec.metadata['changelog_uri'] = 'https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/-/releases'
 
   spec.metadata['rubygems_mfa_required'] = 'false'
 

data/doc/defining-policies.md

@@ -124,6 +124,42 @@ rule { old_enough_to_drive }.policy do
 end
 ```
 
+#### `prevent_all`
+
+To prevent all abilities at once, use `prevent_all`:
+
+```ruby
+rule { banned }.prevent_all
+```
+
+This is equivalent to adding a `prevent` for every ability in the policy. It is
+commonly used to deny all access when a precondition fails (e.g. a user is
+suspended or a resource is locked).
+
+#### `prevent_all` with exceptions
+
+To prevent all abilities **except** specific ones, pass a block with `except`
+declarations:
+
+```ruby
+rule { suspended }.prevent_all do
+  except :read
+  except :appeal_suspension
+end
+```
+
+Multiple abilities can also be listed in a single `except` call:
+
+```ruby
+rule { suspended }.prevent_all do
+  except :read, :list, :appeal_suspension
+end
+```
+
+Excepted abilities are excluded from the blanket prevent and follow normal
+enable/prevent evaluation. Non-excepted abilities are prevented when the rule's
+condition holds, regardless of any `enable` rules.
+
 Rule blocks do not have access to the internal state of the policy, and cannot
 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

data/lib/declarative_policy/base.rb

@@ -6,6 +6,8 @@ module DeclarativePolicy
     # or :prevent actions. Used to look up which rules apply to
     # a given ability. See Base.ability_map
     class AbilityMap
+      EMPTY_ACTIONS = [].freeze
+
       attr_reader :map
 
       def initialize(map = {})
@@ -20,16 +22,31 @@ module DeclarativePolicy
         AbilityMap.new(@map.merge(other.map, &conflict_proc))
       end
 
+      # Does not add the ability if it is missing. An application may check
+      # abilities named by user input, and storing those would grow the map
+      # without limit.
       def actions(key)
-        @map[key] ||= []
+        @map[key] || EMPTY_ACTIONS
+      end
+
+      def key?(key)
+        @map.key?(key)
       end
 
       def enable(key, rule)
-        actions(key) << [:enable, rule]
+        rules_for(key) << [:enable, rule]
       end
 
       def prevent(key, rule)
-        actions(key) << [:prevent, rule]
+        rules_for(key) << [:prevent, rule]
+      end
+
+      private
+
+      # The writer's counterpart to #actions: this one does create the list,
+      # because a rule has to be appended to something.
+      def rules_for(key)
+        @map[key] ||= []
       end
     end
 
@@ -51,18 +68,25 @@ module DeclarativePolicy
       end
     end
 
+    # Counts declarations across all policies, so the caches below can tell
+    # that something was declared since they were built. Without it a policy
+    # loaded or reopened later would be seen with an out of date set of rules.
+    @definition_generation = 0
+
     class << self
       # 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.
+      #
+      # The combined result is cached because rebuilding it is expensive, and
+      # every policy object would otherwise redo it, once per subject when
+      # authorizing a batch.
       def ability_map
-        if self == Base
-          own_ability_map
-        else
-          superclass.ability_map.merge(own_ability_map)
-        end
+        return own_ability_map if self == Base
+
+        memoized_definition(:ability_map) { superclass.ability_map.merge(own_ability_map) }
       end
 
       def own_ability_map
@@ -71,11 +95,9 @@ module DeclarativePolicy
 
       # an inheritable map of conditions, by name
       def conditions
-        if self == Base
-          own_conditions
-        else
-          superclass.conditions.merge(own_conditions)
-        end
+        return own_conditions if self == Base
+
+        memoized_definition(:conditions) { superclass.conditions.merge(own_conditions) }
       end
 
       def own_conditions
@@ -86,11 +108,9 @@ module DeclarativePolicy
       # stored in `ability_map` because they aren't indexed by a particular
       # ability.
       def global_actions
-        if self == Base
-          own_global_actions
-        else
-          superclass.global_actions + own_global_actions
-        end
+        return own_global_actions if self == Base
+
+        memoized_definition(:global_actions) { superclass.global_actions + own_global_actions }
       end
 
       def own_global_actions
@@ -100,22 +120,37 @@ module DeclarativePolicy
       # an inheritable map of delegations, indexed by name (which may be
       # autogenerated)
       def delegations
-        if self == Base
-          own_delegations
-        else
-          superclass.delegations.merge(own_delegations)
-        end
+        return own_delegations if self == Base
+
+        memoized_definition(:delegations) { superclass.delegations.merge(own_delegations) }
       end
 
       def own_delegations
         @own_delegations ||= {}
       end
 
+      # How many declarations (conditions, rules, delegations) have been made
+      # across all policies so far. Save this value and compare it later to
+      # tell whether any policy has been defined or reopened since.
+      def definition_generation
+        Base.instance_variable_get(:@definition_generation)
+      end
+
+      # Clears the cached results for every policy class. Declaration methods
+      # like condition and enable_when call this for you; call it yourself
+      # only if you write to own_conditions and friends directly.
+      def invalidate_definitions!
+        Base.instance_variable_set(:@definition_generation, definition_generation + 1)
+      end
+
       # 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.
+      # ones, filtering out any global actions that have excepted this ability.
       def configuration_for(ability)
-        ability_map.actions(ability) + global_actions
+        return build_configuration_for(ability) unless ability_map.key?(ability)
+
+        configurations = memoized_definition(:configurations) { {} }
+        configurations[ability] ||= build_configuration_for(ability)
       end
 
       ### declaration methods ###
@@ -134,6 +169,7 @@ module DeclarativePolicy
         # rubocop: enable GitlabSecurity/PublicSend
 
         own_delegations[name] = delegation_block
+        invalidate_definitions!
       end
 
       # Declare that the given abilities should not be read from delegates.
@@ -196,6 +232,7 @@ module DeclarativePolicy
         condition = Condition.new(condition_name, condition_options(opts), &value)
 
         own_conditions[condition_name] = condition
+        invalidate_definitions!
 
         define_method(:"#{condition_name}?") { condition(condition_name).pass? }
       end
@@ -207,20 +244,51 @@ module DeclarativePolicy
       # symbol indicating :prevent or :enable.
       def enable_when(abilities, rule)
         abilities.each { |a| own_ability_map.enable(a, rule) }
+        invalidate_definitions!
       end
 
       def prevent_when(abilities, rule)
         abilities.each { |a| own_ability_map.prevent(a, rule) }
+        invalidate_definitions!
       end
 
       # we store global prevents (from `prevent_all`) separately,
       # so that they can be combined into every decision made.
-      def prevent_all_when(rule)
-        own_global_actions << [:prevent, rule]
+      # The optional `except` parameter is a Set of abilities
+      # that should be excluded from the blanket prevent.
+      def prevent_all_when(rule, except: nil)
+        own_global_actions << [:prevent, rule, except]
+        invalidate_definitions!
       end
 
       private
 
+      def build_configuration_for(ability)
+        applicable_globals = global_actions.filter_map do |(action, rule, exceptions)|
+          next if exceptions&.include?(ability)
+
+          [action, rule]
+        end
+
+        (ability_map.actions(ability) + applicable_globals).freeze
+      end
+
+      # Caches this class's combined result (its own declarations plus its
+      # superclass's) until any policy anywhere declares something new.
+      def memoized_definition(name)
+        generation = Base.definition_generation
+
+        unless @memoized_definitions_at == generation
+          @definitions = {}
+          @memoized_definitions_at = generation
+        end
+
+        defs = @definitions
+        return defs[name] if defs.key?(name)
+
+        defs.store(name, yield)
+      end
+
       # 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.
@@ -255,6 +323,8 @@ module DeclarativePolicy
     # 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.
     def allowed?(*abilities)
+      return false if abilities.empty?
+
       abilities.all? { |a| runner(a).pass? }
     end
 
@@ -343,16 +413,34 @@ module DeclarativePolicy
       @_conditions ||= {}
       @_conditions[name] ||=
         begin
-          raise "invalid condition #{name}" unless self.class.conditions.key?(name)
+          definition = self.class.conditions[name]
+          raise "invalid condition #{name}" unless definition
 
-          ManifestCondition.new(self.class.conditions[name], self)
+          ManifestCondition.new(definition, self)
         end
     end
 
+    def user_cache_key
+      @user_cache_key ||= Cache.user_key(@user)
+    end
+
+    def subject_cache_key
+      @subject_cache_key ||= Cache.subject_key(@subject)
+    end
+
     # 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.
+    # Only considers global actions with no exceptions (a prevent_all with
+    # exceptions cannot fully ban, since the excepted abilities may still pass).
     def banned?
-      global_steps = self.class.global_actions.map { |(action, rule)| Step.new(self, rule, action) }
+      global_steps = self.class.global_actions.filter_map do |(action, rule, exceptions)|
+        next if exceptions && !exceptions.empty?
+
+        Step.new(self, rule, action)
+      end
+
+      return false if global_steps.empty?
+
       !Runner.new(global_steps).pass?
     end
 

data/lib/declarative_policy/condition.rb

@@ -7,7 +7,7 @@ module DeclarativePolicy
   # declaration. It holds on to the block to be instance_eval'd
   # on a context (instance of Base) later, via #compute.
   class Condition
-    attr_reader :name, :description, :scope, :manual_score, :context_key
+    attr_reader :name, :description, :scope, :manual_score, :context_key, :key
 
     VALID_SCOPES = %i[user_and_subject user subject global].freeze
     ALLOWED_SCOPES = VALID_SCOPES + %i[normal]
@@ -20,16 +20,13 @@ module DeclarativePolicy
       @description = opts.delete(:description)
       @context_key = opts[:context_key]
       @manual_score = opts.fetch(:score, nil)
+      @key = "#{@context_key}/#{@name}".freeze
     end
 
     def compute(context)
       !!context.instance_eval(&@compute)
     end
 
-    def key
-      "#{@context_key}/#{@name}"
-    end
-
     private
 
     def fetch_scope(options)
@@ -107,17 +104,17 @@ module DeclarativePolicy
         when :user    then "/dp/condition/#{@condition.key}/#{user_key}"
         when :subject then "/dp/condition/#{@condition.key}/#{subject_key}"
         else "/dp/condition/#{@condition.key}/#{user_key},#{subject_key}"
-        end
+        end.freeze
     end
 
     private
 
     def user_key
-      Cache.user_key(@context.user)
+      @context.user_cache_key
     end
 
     def subject_key
-      Cache.subject_key(@context.subject)
+      @context.subject_cache_key
     end
   end
 end

data/lib/declarative_policy/policy_dsl.rb

@@ -29,8 +29,14 @@ module DeclarativePolicy
       @context_class.prevent_when(abilities, @rule)
     end
 
-    def prevent_all
-      @context_class.prevent_all_when(@rule)
+    def prevent_all(&block)
+      if block
+        dsl = PreventAllDsl.new
+        dsl.instance_eval(&block)
+        @context_class.prevent_all_when(@rule, except: dsl.exceptions)
+      else
+        @context_class.prevent_all_when(@rule)
+      end
     end
 
     def method_missing(msg, ...)

data/lib/declarative_policy/prevent_all_dsl.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module DeclarativePolicy
+  # A small DSL class used within a prevent_all { ... } block
+  # to capture exception abilities.
+  #
+  # Usage:
+  #   rule { some_condition }.prevent_all do
+  #     except :read
+  #     except :list
+  #   end
+  class PreventAllDsl
+    attr_reader :exceptions
+
+    def initialize
+      @exceptions = Set.new
+    end
+
+    def except(*abilities)
+      @exceptions.merge(abilities)
+    end
+  end
+end

data/lib/declarative_policy/runner.rb

@@ -5,12 +5,10 @@ require 'set'
 module DeclarativePolicy
   class Runner
     class State
-      attr_reader :called_conditions
-
       def initialize
         @enabled = false
         @prevented = false
-        @called_conditions = Set.new
+        @called = nil
       end
 
       def enable!
@@ -34,7 +32,31 @@ module DeclarativePolicy
       end
 
       def register(manifest_condition)
-        @called_conditions << manifest_condition.cache_key
+        called[manifest_condition.cache_key] = true
+      end
+
+      def called_conditions
+        return Set.new unless @called
+
+        Set.new(@called.keys)
+      end
+
+      def absorb(other)
+        return if other.equal?(self) || other.called_any.nil?
+
+        called.update(other.called_any)
+      end
+
+      protected
+
+      def called_any
+        @called
+      end
+
+      private
+
+      def called
+        @called ||= {}
       end
     end
 
@@ -81,7 +103,7 @@ module DeclarativePolicy
       run unless cached?
 
       parent_state = Thread.current[:declarative_policy_current_runner_state]
-      parent_state&.called_conditions&.merge(@state.called_conditions)
+      parent_state&.absorb(@state)
 
       @state.pass?
     end
@@ -175,49 +197,53 @@ module DeclarativePolicy
         return
       end
 
-      remaining_steps = Set.new(@steps)
-      remaining_enablers, remaining_preventers = remaining_steps.partition(&:enable?).map { |s| Set.new(s) }
+      remaining = @steps.uniq
+      enablers_left = remaining.count(&:enable?)
+      preventers_only = false
 
       loop do
         if @state.enabled?
           # Once we set this, we never need to unset it, because a single
           # prevent will stop this from being enabled
-          remaining_steps = remaining_preventers
-        elsif remaining_enablers.empty?
+          unless preventers_only
+            remaining.reject!(&:enable?)
+            preventers_only = true
+          end
+        elsif enablers_left.zero?
           # if the permission hasn't yet been enabled and we only have
           # prevent steps left, we short-circuit the state here
           @state.prevent!
           return unless debugging
         end
 
-        return if remaining_steps.empty?
+        return if remaining.empty?
 
-        next_step, lowest_score = next_step_and_score(remaining_steps)
-
-        [remaining_steps, remaining_enablers, remaining_preventers].each do |set|
-          set.delete(next_step)
-        end
+        lowest_index, lowest_score = cheapest_step(remaining)
+        step = remaining.delete_at(lowest_index)
+        enablers_left -= 1 if step.enable?
 
-        yield next_step, lowest_score
+        yield step, lowest_score
       end
     end
 
-    def next_step_and_score(remaining_steps)
+    def cheapest_step(remaining)
       lowest_score = Float::INFINITY
-      next_step = nil
+      lowest_index = 0
+      index = 0
 
-      remaining_steps.each do |step|
-        score = step.score
+      while index < remaining.size
+        score = remaining[index].score
 
         if score < lowest_score
-          next_step = step
           lowest_score = score
+          lowest_index = index
+          break if score.zero?
         end
 
-        break if lowest_score.zero?
+        index += 1
       end
 
-      [next_step, lowest_score]
+      [lowest_index, lowest_score]
     end
 
     # Formatter for debugging output.

data/lib/declarative_policy/version.rb

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

data/lib/declarative_policy.rb

@@ -4,6 +4,7 @@ require 'set'
 require_relative 'declarative_policy/cache'
 require_relative 'declarative_policy/condition'
 require_relative 'declarative_policy/delegate_dsl'
+require_relative 'declarative_policy/prevent_all_dsl'
 require_relative 'declarative_policy/policy_dsl'
 require_relative 'declarative_policy/rule_dsl'
 require_relative 'declarative_policy/preferred_scope'
@@ -36,7 +37,7 @@ module DeclarativePolicy
       policies = cache.select { |k, _| k.is_a?(String) && k.start_with?('/dp/policy/') }
 
       policies.each_value do |policy|
-        policy.runners.each do |runner|
+        policy.runners.each_value do |runner|
           runner.uncache! if keys.intersect?(runner.dependencies)
         end
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: declarative_policy
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.2.0
 platform: ruby
 authors:
 - group::authorization
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-23 00:00:00.000000000 Z
+date: 2026-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
@@ -140,6 +140,7 @@ files:
 - lib/declarative_policy/nil_policy.rb
 - lib/declarative_policy/policy_dsl.rb
 - lib/declarative_policy/preferred_scope.rb
+- lib/declarative_policy/prevent_all_dsl.rb
 - lib/declarative_policy/rule.rb
 - lib/declarative_policy/rule_dsl.rb
 - lib/declarative_policy/runner.rb
@@ -151,7 +152,7 @@ licenses:
 metadata:
   homepage_uri: https://gitlab.com/gitlab-org/ruby/gems/declarative-policy
   source_code_uri: https://gitlab.com/gitlab-org/ruby/gems/declarative-policy
-  changelog_uri: https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/-/blob/main/CHANGELOG.md
+  changelog_uri: https://gitlab.com/gitlab-org/ruby/gems/declarative-policy/-/releases
   rubygems_mfa_required: 'false'
 post_install_message:
 rdoc_options: []