action_policy 0.5.0 → 0.5.5

data/lib/.rbnext/3.0/action_policy/policy/core.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "action_policy/behaviours/policy_for"
+require "action_policy/policy/execution_result"
+require "action_policy/utils/suggest_message"
+require "action_policy/utils/pretty_print"
+
+unless "".respond_to?(:underscore)
+  require "action_policy/ext/string_underscore"
+  using ActionPolicy::Ext::StringUnderscore
+end
+
+module ActionPolicy
+  using RubyNext
+
+  # Raised when `resolve_rule` failed to find an approriate
+  # policy rule method for the activity
+  class UnknownRule < Error
+    include ActionPolicy::SuggestMessage
+
+    attr_reader :policy, :rule, :message
+
+    def initialize(policy, rule)
+      @policy = policy.class
+      @rule = rule
+      @message =
+        "Couldn't find rule '#{@rule}' for #{@policy}" \
+        "#{suggest(@rule, @policy.instance_methods - Object.instance_methods)}"
+    end
+  end
+
+  module Policy
+    # Core policy API
+    module Core
+      class << self
+        def included(base)
+          base.extend ClassMethods
+
+          # Generate a new class for each _policy chain_
+          # in order to extend it independently
+          base.module_eval do
+            @result_class = Class.new(ExecutionResult)
+
+            # we need to make this class _named_,
+            # 'cause anonymous classes couldn't be marshalled
+            base.const_set(:APR, @result_class)
+          end
+        end
+      end
+
+      module ClassMethods # :nodoc:
+        attr_writer :identifier
+
+        def result_class
+          return @result_class if instance_variable_defined?(:@result_class)
+          @result_class = superclass.result_class
+        end
+
+        def identifier
+          return @identifier if instance_variable_defined?(:@identifier)
+
+          @identifier = name.sub(/Policy$/, "").underscore.to_sym
+        end
+      end
+
+      include ActionPolicy::Behaviours::PolicyFor
+
+      attr_reader :record, :result
+
+      # NEXT_RELEASE: deprecate `record` arg, migrate to `record: nil`
+      def initialize(record = nil, *)
+        @record = record
+      end
+
+      # Returns a result of applying the specified rule (true of false).
+      # Unlike simply calling a predicate rule (`policy.manage?`),
+      # `apply` also calls pre-checks.
+      def apply(rule)
+        @result = self.class.result_class.new(self.class, rule)
+
+        catch :policy_fulfilled do
+          result.load __apply__(rule)
+        end
+
+        result.value
+      end
+
+      def deny!
+        result&.load false
+        throw :policy_fulfilled
+      end
+
+      def allow!
+        result&.load true
+        throw :policy_fulfilled
+      end
+
+      # This method performs the rule call.
+      # Override or extend it to provide custom functionality
+      # (such as caching, pre checks, etc.)
+      def __apply__(rule) ;  public_send(rule); end
+
+      # Wrap code that could modify result
+      # to prevent the current result modification
+      def with_clean_result # :nodoc:
+        was_result = @result
+        yield
+        @result
+      ensure
+        @result = was_result
+      end
+
+      # Returns a result of applying the specified rule to the specified record.
+      # Under the hood a policy class for record is resolved
+      # (unless it's explicitly set through `with` option).
+      #
+      # If record is `nil` then we uses the current policy.
+      def allowed_to?(rule, record = :__undef__, **options)
+        if (record == :__undef__ || record == self.record) && options.empty?
+          __apply__(resolve_rule(rule))
+        else
+          policy_for(record: record, **options).then do |policy|
+            policy.apply(policy.resolve_rule(rule))
+          end
+        end
+      end
+
+      # An alias for readability purposes
+      def check?(*args) ;  allowed_to?(*args); end
+
+      # Returns a rule name (policy method name) for activity.
+      #
+      # By default, rule name is equal to activity name.
+      #
+      # Raises ActionPolicy::UknownRule when rule is not found in policy.
+      def resolve_rule(activity)
+        raise UnknownRule.new(self, activity) unless
+          respond_to?(activity)
+        activity
+      end
+
+      # Return annotated source code for the rule
+      # NOTE: require "method_source" and "unparser" gems to be installed.
+      # Otherwise returns empty string.
+      def inspect_rule(rule) ;  PrettyPrint.print_method(self, rule); end
+
+      # Helper for printing the annotated rule source.
+      # Useful for debugging: type `pp :show?` within the context of the policy
+      # to preview the rule.
+      def pp(rule)
+        with_clean_result do
+          # We need result to exist for `allowed_to?` to work correctly
+          @result = self.class.result_class.new(self.class, rule)
+          header = "#{self.class.name}##{rule}"
+          source = inspect_rule(rule)
+          $stdout.puts "#{header}\n#{source}"
+        end
+      end
+    end
+  end
+end

data/lib/.rbnext/3.0/action_policy/policy/defaults.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  module Policy
+    # Create default rules and aliases:
+    # - `index?` (=`false`)
+    # - `create?` (=`false`)
+    # - `new?` as an alias for `create?`
+    # - `manage?` as a fallback for all unspecified rules (default rule)
+    module Defaults
+      def self.included(base)
+        raise "Aliases support is required for defaults" unless
+          base.ancestors.include?(Aliases)
+
+        base.default_rule :manage?
+        base.alias_rule :new?, to: :create?
+
+        raise "Verification context support is required for defaults" unless
+          base.ancestors.include?(Aliases)
+
+        base.authorize :user
+      end
+
+      def index?() ;  false; end
+
+      def create?() ;  false; end
+
+      def manage?() ;  false; end
+    end
+  end
+end

data/lib/.rbnext/3.0/action_policy/policy/execution_result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  module Policy
+    # Result of applying a policy rule
+    #
+    # This class could be extended by some modules to provide
+    # additional functionality
+    class ExecutionResult
+      attr_reader :value, :policy, :rule
+
+      def initialize(policy, rule)
+        @policy = policy
+        @rule = rule
+      end
+
+      # Populate the final value
+      def load(value)
+        @value = value
+      end
+
+      def success?() ;  @value == true; end
+
+      def fail?() ;  @value == false; end
+
+      def cached!
+        @cached = true
+      end
+
+      def cached?() ;  @cached == true; end
+
+      def inspect
+        "<#{policy}##{rule}: #{@value}>"
+      end
+    end
+  end
+end

data/lib/.rbnext/3.0/action_policy/policy/pre_check.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  module Policy
+    # Adds callback-style checks to policies to
+    # extract common checks from rules.
+    #
+    #    class ApplicationPolicy < ActionPolicy::Base
+    #      authorize :user
+    #      pre_check :allow_admins
+    #
+    #      private
+    #        # Allow every action for admins
+    #        def allow_admins
+    #          allow! if user.admin?
+    #        end
+    #    end
+    #
+    # You can specify conditional pre-checks (through `except` / `only`) options
+    # and skip already defined pre-checks if necessary.
+    #
+    #    class UserPolicy < ApplicationPolicy
+    #      skip_pre_check :allow_admins, only: :destroy?
+    #
+    #      def destroy?
+    #        user.admin? && !record.admin?
+    #      end
+    #    end
+    module PreCheck
+      # Single pre-check instance.
+      #
+      # Implements filtering logic.
+      class Check
+        attr_reader :name, :policy_class
+
+        def initialize(policy, name, except: nil, only: nil)
+          if !except.nil? && !only.nil?
+            raise ArgumentError,
+              "Only one of `except` and `only` may be specified for pre-check"
+          end
+
+          @policy_class = policy
+          @name = name
+          @blacklist = Array(except) unless except.nil?
+          @whitelist = Array(only) unless only.nil?
+
+          rebuild_filter
+        end
+
+        def applicable?(rule)
+          return true if filter.nil?
+          filter.call(rule)
+        end
+
+        def call(policy) ;  policy.send(name); end
+
+        def skip!(except: nil, only: nil)
+          if !except.nil? && !only.nil?
+            raise ArgumentError,
+              "Only one of `except` and `only` may be specified when skipping pre-check"
+          end
+
+          if except.nil? && only.nil?
+            raise ArgumentError,
+              "At least one of `except` and `only` must be specified when skipping pre-check"
+          end
+
+          if except
+            @whitelist = Array(except)
+            @whitelist -= blacklist if blacklist
+            @blacklist = nil
+          else
+            # only
+            @blacklist += Array(only) if blacklist
+            @whitelist -= Array(only) if whitelist
+            @blacklist = Array(only) if filter.nil?
+          end
+
+          rebuild_filter
+        end
+        # rubocop: enable
+        # rubocop: enable
+
+        def dup
+          self.class.new(
+            policy_class,
+            name,
+            except: blacklist&.dup,
+            only: whitelist&.dup
+          )
+        end
+
+        private
+
+        attr_reader :whitelist, :blacklist, :filter
+
+        def rebuild_filter
+          @filter =
+            if whitelist
+              proc { |rule| whitelist.include?(rule) }
+            elsif blacklist
+              proc { |rule| !blacklist.include?(rule) }
+            end
+        end
+      end
+
+      class << self
+        def included(base)
+          base.extend ClassMethods
+        end
+      end
+
+      def run_pre_checks(rule)
+        self.class.pre_checks.each do |check|
+          next unless check.applicable?(rule)
+          check.call(self)
+        end
+
+        yield if block_given?
+      end
+
+      def __apply__(rule)
+        run_pre_checks(rule) { super }
+      end
+
+      module ClassMethods # :nodoc:
+        def pre_check(*names, **options)
+          names.each do |name|
+            # do not allow pre-check override
+            check = pre_checks.find { _1.name == name }
+            raise "Pre-check already defined: #{name}" unless check.nil?
+
+            pre_checks << Check.new(self, name, **options)
+          end
+        end
+
+        def skip_pre_check(*names, **options)
+          names.each do |name|
+            check = pre_checks.find { _1.name == name }
+            raise "Pre-check not found: #{name}" if check.nil?
+
+            # when no options provided we remove this check completely
+            next pre_checks.delete(check) if options.empty?
+
+            # otherwise duplicate and apply skip options
+            pre_checks[pre_checks.index(check)] = check.dup.tap { _1.skip!(**options) }
+          end
+        end
+
+        def pre_checks
+          return @pre_checks if instance_variable_defined?(:@pre_checks)
+
+          @pre_checks = if superclass.respond_to?(:pre_checks)
+            superclass.pre_checks.dup
+          else
+            []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/.rbnext/3.0/action_policy/policy/reasons.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  using RubyNext
+
+  module Policy
+    # Failures reasons store
+    class FailureReasons
+      attr_reader :reasons
+
+      def initialize
+        @reasons = {}
+      end
+
+      def add(policy_or_class, rule, details = nil)
+        policy_class = policy_or_class.is_a?(Module) ? policy_or_class : policy_or_class.class
+        reasons[policy_class] ||= []
+
+        if details.nil?
+          add_non_detailed_reason reasons[policy_class], rule
+        else
+          add_detailed_reason reasons[policy_class], with_details(rule, details)
+        end
+      end
+
+      # Return Hash of the form:
+      #   { policy_identifier => [rules, ...] }
+      def details() ;  reasons.transform_keys(&:identifier); end
+
+      def empty?() ;  reasons.empty?; end
+
+      def present?() ;  !empty?; end
+
+      private
+
+      def add_non_detailed_reason(store, rule)
+        index =
+          if store.last.is_a?(::Hash)
+            store.size - 1
+          else
+            store.size
+          end
+
+        store.insert(index, rule)
+      end
+
+      def add_detailed_reason(store, detailed_rule)
+        store.last.is_a?(::Hash) || store << {}
+        store.last.merge!(detailed_rule)
+      end
+
+      def with_details(rule, details)
+        return rule if details.nil?
+
+        {rule => details}
+      end
+    end
+
+    # Extend ExecutionResult with `reasons` method
+    module ResultFailureReasons
+      def reasons
+        @reasons ||= FailureReasons.new
+      end
+
+      attr_accessor :details
+
+      def clear_details
+        @details = nil
+      end
+
+      # Returns all the details merged together
+      def all_details
+        return @all_details if defined?(@all_details)
+
+        @all_details = {}.tap do |all|
+          next unless defined?(@reasons)
+
+          reasons.reasons.each_value do |rules|
+            detailed_reasons = rules.last
+
+            next unless detailed_reasons.is_a?(Hash)
+
+            detailed_reasons.each_value do |details|
+              all.merge!(details)
+            end
+          end
+        end
+      end
+
+      # Add reasons to inspect
+      def inspect
+        super.then do |str|
+          next str if reasons.empty?
+          str.sub(/>$/, " (reasons: #{reasons.details})")
+        end
+      end
+    end
+
+    # Provides failure reasons tracking functionality.
+    # That allows you to distinguish between the reasons why authorization was rejected.
+    #
+    # It's helpful when you compose policies (i.e. use one policy within another).
+    #
+    # For example:
+    #
+    #   class ApplicantPolicy < ApplicationPolicy
+    #     def show?
+    #       user.has_permission?(:view_applicants) &&
+    #         allowed_to?(:show?, object.stage)
+    #     end
+    #   end
+    #
+    # Now when you receive an exception, you have a reasons object, which contains additional
+    # information about the failure:
+    #
+    #   rescue_from ActionPolicy::Unauthorized do |ex|
+    #     ex.policy #=> ApplicantPolicy
+    #     ex.rule #=> :show?
+    #     ex.result.reasons.details  #=> {stage: [:show?]}
+    #   end
+    #
+    # NOTE: the reason key (`stage`) is a policy identifier (underscored class name by default).
+    # For namespaced policies it has a form of:
+    #
+    #   class Admin::UserPolicy < ApplicationPolicy
+    #     # ..
+    #   end
+    #
+    #   reasons.details #=> {:"admin/user" => [:show?]}
+    #
+    #
+    # You can also wrap _local_ rules into `allowed_to?` to populate reasons:
+    #
+    #   class ApplicantPolicy < ApplicationPolicy
+    #     def show?
+    #       allowed_to?(:view_applicants?) &&
+    #         allowed_to?(:show?, object.stage)
+    #     end
+    #
+    #     def view_applicants?
+    #       user.has_permission?(:view_applicants)
+    #     end
+    #   end
+    #
+    # NOTE: there is `check?` alias for `allowed_to?`.
+    #
+    # You can provide additional details to your failure reasons by using
+    # a `details: { ... }` option:
+    #
+    #   class ApplicantPolicy < ApplicationPolicy
+    #     def show?
+    #       allowed_to?(:show?, object.stage)
+    #     end
+    #   end
+    #
+    #   class StagePolicy < ApplicationPolicy
+    #     def show?
+    #       # Add stage title to the failure reason (if any)
+    #       # (could be used by client to show more descriptive message)
+    #       details[:title] = record.title
+    #
+    #       # then perform the checks
+    #       user.stages.where(id: record.id).exists?
+    #     end
+    #   end
+    #
+    #   # when accessing the reasons
+    #   p ex.result.reasons.details #=> { stage: [{show?: {title: "Onboarding"}] }
+    #
+    # NOTE: when using detailed reasons, the `details` array contains as the last element
+    # a hash with ALL details reasons for the policy (in a form of <rule> => <details>).
+    #
+    module Reasons
+      class << self
+        def included(base)
+          base.result_class.prepend(ResultFailureReasons)
+        end
+      end
+
+      # Add additional details to the failure reason
+      def details
+        result.details ||= {}
+      end
+
+      def allowed_to?(rule, record = :__undef__, **options)
+        res =
+          if (record == :__undef__ || record == self.record) && options.empty?
+            rule = resolve_rule(rule)
+            policy = self
+            with_clean_result { apply(rule) }
+          else
+            policy = policy_for(record: record, **options)
+            rule = policy.resolve_rule(rule)
+
+            policy.apply(rule)
+            policy.result
+          end
+
+        result&.reasons&.add(policy, rule, res.details) if res.fail?
+
+        res.clear_details
+
+        res.success?
+      end
+
+      def deny!(reason = nil)
+        result&.reasons&.add(self, reason) if reason
+        super()
+      end
+    end
+  end
+end