declarative_policy 1.0.0

data/lib/declarative_policy/rule_dsl.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module DeclarativePolicy
+  # The DSL evaluation context inside rule { ... } blocks.
+  # Responsible for creating and combining Rule objects.
+  #
+  # See Base.rule
+  class RuleDsl
+    def initialize(context_class)
+      @context_class = context_class
+    end
+
+    def can?(ability)
+      Rule::Ability.new(ability)
+    end
+
+    def all?(*rules)
+      Rule::And.make(rules)
+    end
+
+    def any?(*rules)
+      Rule::Or.make(rules)
+    end
+
+    def none?(*rules)
+      ~Rule::Or.new(rules)
+    end
+
+    def cond(condition)
+      Rule::Condition.new(condition)
+    end
+
+    def delegate(delegate_name, condition)
+      Rule::DelegatedCondition.new(delegate_name, condition)
+    end
+
+    def method_missing(msg, *args)
+      return super unless args.empty? && !block_given?
+
+      if @context_class.delegations.key?(msg)
+        DelegateDsl.new(self, msg)
+      else
+        cond(msg.to_sym)
+      end
+    end
+
+    def respond_to_missing?(symbol, include_all)
+      true
+    end
+  end
+end

data/lib/declarative_policy/runner.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module DeclarativePolicy
+  class Runner
+    class State
+      def initialize
+        @enabled = false
+        @prevented = false
+      end
+
+      def enable!
+        @enabled = true
+      end
+
+      def enabled?
+        @enabled
+      end
+
+      def prevent!
+        @prevented = true
+      end
+
+      def prevented?
+        @prevented
+      end
+
+      def pass?
+        !prevented? && enabled?
+      end
+    end
+
+    # a Runner contains a list of Steps to be run.
+    attr_reader :steps
+
+    def initialize(steps)
+      @steps = steps
+      @state = nil
+    end
+
+    # We make sure only to run any given Runner once,
+    # and just continue to use the resulting @state
+    # that's left behind.
+    def cached?
+      !!@state
+    end
+
+    # used by Rule::Ability. See #steps_by_score
+    def score
+      return 0 if cached?
+
+      steps.sum(&:score)
+    end
+
+    def merge_runner(other)
+      Runner.new(@steps + other.steps)
+    end
+
+    # The main entry point, called for making an ability decision.
+    # See #run and DeclarativePolicy::Base#can?
+    def pass?
+      run unless cached?
+
+      @state.pass?
+    end
+
+    # see DeclarativePolicy::Base#debug
+    def debug(out = $stderr)
+      run(out)
+    end
+
+    private
+
+    def flatten_steps!
+      @steps = @steps.flat_map { |s| s.flattened(@steps) }
+    end
+
+    # This method implements the semantic of "one enable and no prevents".
+    # It relies on #steps_by_score for the main loop, and updates @state
+    # with the result of the step.
+    def run(debug = nil)
+      @state = State.new
+
+      steps_by_score do |step, score|
+        break if !debug && @state.prevented?
+
+        passed = nil
+        case step.action
+        when :enable
+          # we only check :enable actions if they have a chance of
+          # changing the outcome - if no other rule has enabled or
+          # prevented.
+          unless @state.enabled? || @state.prevented?
+            passed = step.pass?
+            @state.enable! if passed
+          end
+
+          debug << inspect_step(step, score, passed) if debug
+        when :prevent
+          # we only check :prevent actions if the state hasn't already
+          # been prevented.
+          unless @state.prevented?
+            passed = step.pass?
+            @state.prevent! if passed
+          end
+
+          debug << inspect_step(step, score, passed) if debug
+        else raise "invalid action #{step.action.inspect}"
+        end
+      end
+
+      @state
+    end
+
+    # This is the core spot where all those `#score` methods matter.
+    # It is critical for performance to run steps in the correct order,
+    # so that we don't compute expensive conditions (potentially n times
+    # if we're called on, say, a large list of users).
+    #
+    # In order to determine the cheapest step to run next, we rely on
+    # Step#score, which returns a numerical rating of how expensive
+    # it would be to calculate - the lower the better. It would be
+    # easy enough to statically sort by these scores, but we can do
+    # a little better - the scores are cache-aware (conditions that
+    # are already in the cache have score 0), which means that running
+    # a step can actually change the scores of other steps.
+    #
+    # 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.
+    #
+    # For each step, we yield the step object along with the computed score
+    # for debugging purposes.
+    def steps_by_score
+      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
+
+        return
+      end
+
+      remaining_steps = Set.new(@steps)
+      remaining_enablers, remaining_preventers = remaining_steps.partition(&:enable?).map { |s| Set.new(s) }
+
+      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?
+          # if the permission hasn't yet been enabled and we only have
+          # prevent steps left, we short-circuit the state here
+          @state.prevent!
+        end
+
+        return if remaining_steps.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
+
+        yield next_step, lowest_score
+      end
+    end
+
+    def next_step_and_score(remaining_steps)
+      lowest_score = Float::INFINITY
+      next_step = nil
+
+      remaining_steps.each do |step|
+        score = step.score
+
+        if score < lowest_score
+          next_step = step
+          lowest_score = score
+        end
+
+        break if lowest_score.zero?
+      end
+
+      [next_step, score]
+    end
+
+    # Formatter for debugging output.
+    def inspect_step(step, original_score, passed)
+      symbol =
+        case passed
+        when true then '+'
+        when false then '-'
+        when nil then ' '
+        end
+
+      "#{symbol} [#{original_score.to_i}] #{step.repr}\n"
+    end
+  end
+end

data/lib/declarative_policy/step.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module DeclarativePolicy
+  # This object represents one step in the runtime decision of whether
+  # an ability is allowed. It contains a Rule and a context (instance
+  # of DeclarativePolicy::Base), which contains the user, the subject,
+  # and the cache. It also contains an "action", which is the symbol
+  # :prevent or :enable.
+  class Step
+    attr_reader :context, :rule, :action
+
+    def initialize(context, rule, action)
+      @context = context
+      @rule = rule
+      @action = action
+    end
+
+    # In the flattening process, duplicate steps may be generated in the
+    # same rule. This allows us to eliminate those (see Runner#steps_by_score
+    # and note its use of a Set)
+    def ==(other)
+      @context == other.context && @rule == other.rule && @action == other.action
+    end
+
+    # In the runner, steps are sorted dynamically by score, so that
+    # we are sure to compute them in close to the optimal order.
+    #
+    # See also Rule#score, ManifestCondition#score, and Runner#steps_by_score.
+    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
+    end
+
+    def with_action(action)
+      Step.new(@context, @rule, action)
+    end
+
+    def enable?
+      @action == :enable
+    end
+
+    def prevent?
+      @action == :prevent
+    end
+
+    # This rather complex method allows us to split rules into parts so that
+    # they can be sorted independently for better optimization
+    def flattened(roots)
+      case @rule
+      when Rule::Or
+        # A single `Or` step is the same as each of its elements as separate steps
+        @rule.rules.flat_map { |r| Step.new(@context, r, @action).flattened(roots) }
+      when Rule::Ability
+        # This looks like a weird micro-optimization but it buys us quite a lot
+        # 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) }
+
+        if steps.all?(&:enable?)
+          # in the case that we are a :prevent step, each inlined step becomes
+          # an independent :prevent, even though it was an :enable in its initial
+          # context.
+          steps.map! { |s| s.with_action(:prevent) } if prevent?
+
+          steps.flat_map { |s| s.flattened(roots) }
+        else
+          [self]
+        end
+      else
+        [self]
+      end
+    end
+
+    def pass?
+      @rule.pass?(@context)
+    end
+
+    def repr
+      "#{@action} when #{@rule.repr} (#{@context.repr})"
+    end
+  end
+end

data/lib/declarative_policy/version.rb

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

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: declarative_policy
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jeanine Adkisson
+- Alexis Kalderimis
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-04-12 00:00:00.000000000 Z
+dependencies: []
+description: |
+  This library provides an authorization framework with a declarative DSL
+
+  With this library, you can write permission policies that are separate
+  from business logic.
+
+  This library is in production use at GitLab.com
+email:
+- akalderimis@gitlab.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".gitlab-ci.yml"
+- ".rspec"
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- Dangerfile
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- danger/plugins/project_helper.rb
+- danger/roulette/Dangerfile
+- declarative_policy.gemspec
+- doc/caching.md
+- doc/configuration.md
+- doc/defining-policies.md
+- lib/declarative_policy.rb
+- lib/declarative_policy/base.rb
+- lib/declarative_policy/cache.rb
+- lib/declarative_policy/condition.rb
+- lib/declarative_policy/configuration.rb
+- lib/declarative_policy/delegate_dsl.rb
+- lib/declarative_policy/nil_policy.rb
+- lib/declarative_policy/policy_dsl.rb
+- lib/declarative_policy/preferred_scope.rb
+- lib/declarative_policy/rule.rb
+- lib/declarative_policy/rule_dsl.rb
+- lib/declarative_policy/runner.rb
+- lib/declarative_policy/step.rb
+- lib/declarative_policy/version.rb
+homepage: https://gitlab.com/gitlab-org/declarative-policy
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://gitlab.com/gitlab-org/declarative-policy
+  source_code_uri: https://gitlab.com/gitlab-org/declarative-policy
+  changelog_uri: https://gitlab.com/gitlab-org/declarative-policy/-/blobs/master/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key: 
+specification_version: 4
+summary: An authorization library with a focus on declarative policy definitions.
+test_files: []