declarative_policy 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 704af6c0500c00a0e6c6797dd5b496c098db86f33ccc1ef2496be37e43b33e03
-  data.tar.gz: 2236adb02dbee28b6565fc72541fe2fbee5a087ef15cc2fe1f0d060ce1eece13
+  metadata.gz: 05f875265a827bd025947cd0098d09804051cf0fa2c02857aa230e03d8554f02
+  data.tar.gz: 38452f2308ad61d9cf54bb604f68cbdd73cb75d342ea24a55c265ee708f588b4
 SHA512:
-  metadata.gz: c3841495e1922ae72f704524e40ca080da4838cfe075d401350212f5b31f116f6003aa3e371d2a0084a11986b4745bb82946ad84b61247a19b59470a26e24755
-  data.tar.gz: f3f0d97ba2b9e56079d5307c135ec2b15c73759661f32e6cda2db44ab0fa21002598725cf0c762ca85c0580ae1c5b7c397115f185ec94c9da600cfaf19f6e590
+  metadata.gz: 82ac859206da667fb45b59662aa9a35fb760f59179e0976f9e7ed9ffba92259ba271fa6732ec9b84e3e14e14961f1362fb13077deb7191c75436c83ef60ab342
+  data.tar.gz: c9e41debc20ab2ecc2dc8da44c2e782f50e58ec7d9cba23986c5494c7c00d334de82a3f6f2c9a5b35739a402ecc097f144cb05314ab8584f07aa46dab548b6c0

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

@@ -113,9 +113,15 @@ module DeclarativePolicy
 
       # 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
+        applicable_globals = global_actions.filter_map do |(action, rule, exceptions)|
+          next if exceptions&.include?(ability)
+
+          [action, rule]
+        end
+
+        ability_map.actions(ability) + applicable_globals
       end
 
       ### declaration methods ###
@@ -215,8 +221,10 @@ module DeclarativePolicy
 
       # 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]
       end
 
       private
@@ -255,6 +263,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
 
@@ -351,8 +361,17 @@ module DeclarativePolicy
 
     # 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/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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeclarativePolicy
-  VERSION = '2.0.1'
+  VERSION = '2.1.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'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: declarative_policy
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - group::authorization
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-23 00:00:00.000000000 Z
+date: 2026-03-13 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: []