action_policy 0.5.0 → 0.5.1

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,210 @@
+# 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?
+            policy = self
+            with_clean_result { apply(rule) }
+          else
+            policy = policy_for(record: record, **options)
+
+            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

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "action_policy/behaviours/scoping"
+
+require "action_policy/utils/suggest_message"
+
+module ActionPolicy
+  class UnknownScopeType < Error # :nodoc:
+    include ActionPolicy::SuggestMessage
+
+    MESSAGE_TEMPLATE = "Unknown policy scope type :%s for %s%s"
+
+    attr_reader :message
+
+    def initialize(policy_class, type)
+      @message = format(
+        MESSAGE_TEMPLATE,
+        type, policy_class,
+        suggest(type, policy_class.scoping_handlers.keys)
+      )
+    end
+  end
+
+  class UnknownNamedScope < Error # :nodoc:
+    include ActionPolicy::SuggestMessage
+
+    MESSAGE_TEMPLATE = "Unknown named scope :%s for type :%s for %s%s"
+
+    attr_reader :message
+
+    def initialize(policy_class, type, name)
+      @message = format(
+        MESSAGE_TEMPLATE, name, type, policy_class,
+        suggest(name, policy_class.scoping_handlers[type].keys)
+      )
+    end
+  end
+
+  class UnrecognizedScopeTarget < Error # :nodoc:
+    MESSAGE_TEMPLATE = "Couldn't infer scope type for %s instance"
+
+    attr_reader :message
+
+    def initialize(target)
+      target_class = target.is_a?(Module) ? target : target.class
+
+      @message = format(
+        MESSAGE_TEMPLATE, target_class
+      )
+    end
+  end
+
+  module Policy
+    # Scoping is used to modify the _object under authorization_.
+    #
+    # The most common situation is when you want to _scope_ the collection depending
+    # on the current user permissions.
+    #
+    # For example:
+    #
+    #   class ApplicationPolicy < ActionPolicy::Base
+    #     # Scoping only makes sense when you have the authorization context
+    #     authorize :user
+    #
+    #     # :relation here is a scoping type
+    #     scope_for :relation do |relation|
+    #       # authorization context is available within a scope
+    #       if user.admin?
+    #         relation
+    #       else
+    #         relation.publicly_visible
+    #       end
+    #     end
+    #   end
+    #
+    #   base_scope = User.all
+    #   authorized_scope = ApplicantPolicy.new(user: user)
+    #    .apply_scope(base_scope, type: :relation)
+    module Scoping
+      class << self
+        def included(base)
+          base.extend ClassMethods
+        end
+      end
+
+      include ActionPolicy::Behaviours::Scoping
+
+      # Pass target to the scope handler of the specified type and name.
+      # If `name` is not specified then `:default` name is used.
+      # If `type` is not specified then we try to infer the type from the
+      # target class.
+      def apply_scope(target, type:, name: :default, scope_options: nil)
+        raise ActionPolicy::UnknownScopeType.new(self.class, type) unless
+          self.class.scoping_handlers.key?(type)
+
+        raise ActionPolicy::UnknownNamedScope.new(self.class, type, name) unless
+          self.class.scoping_handlers[type].key?(name)
+
+        mid = :"__scoping__#{type}__#{name}"
+        scope_options ? send(mid, target, **scope_options) : send(mid, target)
+      end
+
+      def resolve_scope_type(target)
+        lookup_type_from_target(target) ||
+          raise(ActionPolicy::UnrecognizedScopeTarget, target)
+      end
+
+      def lookup_type_from_target(target)
+        self.class.scope_matchers.detect do |(_type, matcher)|
+          matcher === target
+        end&.first
+      end
+
+      module ClassMethods # :nodoc:
+        # Register a new scoping method for the `type`
+        def scope_for(type, name = :default, &block)
+          mid = :"__scoping__#{type}__#{name}"
+
+          define_method(mid, &block)
+
+          scoping_handlers[type][name] = mid
+        end
+
+        def scoping_handlers
+          return @scoping_handlers if instance_variable_defined?(:@scoping_handlers)
+
+          @scoping_handlers =
+            Hash.new { |h, k| h[k] = {} }.tap do |handlers|
+              if superclass.respond_to?(:scoping_handlers)
+                superclass.scoping_handlers.each do |k, v|
+                  handlers[k] = v.dup
+                end
+              end
+            end
+        end
+
+        # Define scope type matcher.
+        #
+        # Scope matcher is an object that implements `#===` (_case equality_) or a Proc.
+        #
+        # When no type is provided when applying a scope we try to infer a type
+        # from the target object by calling matchers one by one until we find a matching
+        # type (i.e. there is a matcher which returns `true` when applying it to the target).
+        def scope_matcher(type, class_or_proc)
+          scope_matchers << [type, class_or_proc]
+        end
+
+        def scope_matchers
+          return @scope_matchers if instance_variable_defined?(:@scope_matchers)
+
+          @scope_matchers = if superclass.respond_to?(:scope_matchers)
+            superclass.scope_matchers.dup
+          else
+            []
+          end
+        end
+      end
+    end
+  end
+end