action_policy 0.2.4 → 0.3.0.beta1

data/lib/action_policy/policy/reasons.rb

@@ -1,5 +1,15 @@
 # frozen_string_literal: true
 
+unless "".respond_to?(:then)
+  require "action_policy/ext/yield_self_then"
+  using ActionPolicy::Ext::YieldSelfThen
+end
+
+unless {}.respond_to?(:transform_keys)
+  require "action_policy/ext/hash_transform_keys"
+  using ActionPolicy::Ext::HashTransformKeys
+end
+
 module ActionPolicy
   module Policy
     # Failures reasons store
@@ -10,10 +20,15 @@ module ActionPolicy
         @reasons = {}
       end
 
-      def add(policy_or_class, rule)
+      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] ||= []
-        reasons[policy_class] << rule
+
+        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:
@@ -29,6 +44,30 @@ module ActionPolicy
       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
@@ -36,6 +75,20 @@ module ActionPolicy
       def reasons
         @reasons ||= FailureReasons.new
       end
+
+      attr_accessor :details
+
+      def clear_details
+        @details = nil
+      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.
@@ -58,7 +111,7 @@ module ActionPolicy
     #   rescue_from ActionPolicy::Unauthorized do |ex|
     #     ex.policy #=> ApplicantPolicy
     #     ex.rule #=> :show?
-    #     ex.result.reasons.details  #=> { stage: [:show?] }
+    #     ex.result.reasons.details  #=> {stage: [:show?]}
     #   end
     #
     # NOTE: the reason key (`stage`) is a policy identifier (underscored class name by default).
@@ -68,7 +121,7 @@ module ActionPolicy
     #     # ..
     #   end
     #
-    #   reasons.details #=> { :"admin/user" => [:show?] }
+    #   reasons.details #=> {:"admin/user" => [:show?]}
     #
     #
     # You can also wrap _local_ rules into `allowed_to?` to populate reasons:
@@ -83,18 +136,49 @@ module ActionPolicy
     #       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.include(ResultFailureReasons)
+          base.result_class.prepend(ResultFailureReasons)
         end
       end
 
-      # rubocop: disable Metrics/MethodLength
-      def allowed_to?(rule, record = :__undef__, **options)
-        policy = nil
+      # Add additional details to the failure reason
+      def details
+        result.details ||= {}
+      end
 
-        succeed =
+      def allowed_to?(rule, record = :__undef__, **options)
+        res =
           if record == :__undef__
             policy = self
             with_clean_result { apply(rule) }
@@ -102,12 +186,15 @@ module ActionPolicy
             policy = policy_for(record: record, **options)
 
             policy.apply(rule)
+            policy.result
           end
 
-        result.reasons.add(policy, rule) unless succeed
-        succeed
+        result.reasons.add(policy, rule, res.details) if res.fail?
+
+        res.clear_details
+
+        res.success?
       end
-      # rubocop: enable Metrics/MethodLength
     end
   end
 end

data/lib/action_policy/policy/scoping.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "action_policy/behaviours/scoping"
+
+require "action_policy/utils/suggest_message"
+
+require "action_policy/ext/proc_case_eq"
+
+using ActionPolicy::Ext::ProcCaseEq
+
+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] = {} }
+
+          if superclass.respond_to?(:scoping_handlers)
+            superclass.scoping_handlers.each do |k, v|
+              @scoping_handlers[k] = v.dup
+            end
+          end
+
+          @scoping_handlers
+        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 = []
+
+          @scope_matchers = superclass.scope_matchers.dup if superclass.respond_to?(:scope_matchers)
+
+          @scope_matchers
+        end
+      end
+    end
+  end
+end

data/lib/action_policy/rails/authorizer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActionPolicy # :nodoc:
+  module Rails
+    # Add instrumentation for `authorize!` method
+    module Authorizer
+      EVENT_NAME = "action_policy.authorize"
+
+      def authorize(policy, rule)
+        event = {policy: policy.class.name, rule: rule.to_s}
+        ActiveSupport::Notifications.instrument(EVENT_NAME, event) do
+          res = super
+          event[:cached] = policy.result.cached?
+          event[:value] = policy.result.value
+          res
+        end
+      end
+    end
+  end
+end

data/lib/action_policy/rails/controller.rb

@@ -42,9 +42,6 @@ module ActionPolicy
     #
     # Raises `ActionPolicy::Unauthorized` if check failed.
     def authorize!(record = :__undef__, to: nil, **options)
-      record = controller_name.classify.safe_constantize if
-        record == :__undef__
-
       to ||= :"#{action_name}?"
 
       super(record, to: to, **options)
@@ -52,17 +49,10 @@ module ActionPolicy
       self.authorize_count += 1
     end
 
-    # Checks that an activity is allowed for the current context (e.g. user).
-    #
-    # If record is not provided, tries to infer the resource class
-    # from controller name (i.e. `controller_name.classify.safe_constantize`).
-    #
-    # Returns true of false.
-    def allowed_to?(rule, record = :__undef__, **options)
-      record = controller_name.classify.safe_constantize if
-        record == :__undef__
-
-      super(rule, record, **options)
+    # Tries to infer the resource class from controller name
+    # (i.e. `controller_name.classify.safe_constantize`).
+    def implicit_authorization_target
+      controller_name.classify.safe_constantize
     end
 
     def verify_authorized

data/lib/action_policy/rails/ext/active_record.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Add explicit #policy_cache_key to Relation to
+# avoid calling #cache_key.
+# See https://github.com/palkan/action_policy/issues/55
+ActiveRecord::Relation.include(Module.new do
+  def policy_cache_key
+    object_id
+  end
+end)

data/lib/action_policy/rails/policy/instrumentation.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ActionPolicy # :nodoc:
+  module Policy
+    module Rails
+      # Add ActiveSupport::Notifications support.
+      #
+      # Fires `action_policy.apply_rule` event on every `#apply` call.
+      module Instrumentation
+        EVENT_NAME = "action_policy.apply_rule"
+
+        def apply(rule)
+          event = {policy: self.class.name, rule: rule.to_s}
+          ActiveSupport::Notifications.instrument(EVENT_NAME, event) do
+            res = super
+            event[:cached] = result.cached?
+            event[:value] = result.value
+            res
+          end
+        end
+      end
+    end
+  end
+end

data/lib/action_policy/rails/scope_matchers/action_controller_params.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  module ScopeMatchers
+    # Adds `params_filter` method as an alias
+    # for `scope_for :action_controller_params`
+    module ActionControllerParams
+      def params_filter(*args, &block)
+        scope_for :action_controller_params, *args, &block
+      end
+    end
+  end
+end
+
+# Register params scope matcher
+ActionPolicy::Base.scope_matcher :action_controller_params, ActionController::Parameters
+
+# Add alias to base policy
+ActionPolicy::Base.extend ActionPolicy::ScopeMatchers::ActionControllerParams