pundit 2.4.0 → 2.5.0

data/lib/pundit/authorization.rb

@@ -1,6 +1,14 @@
 # frozen_string_literal: true
 
 module Pundit
+  # Pundit DSL to include in your controllers to provide authorization helpers.
+  #
+  # @example
+  #   class ApplicationController < ActionController::Base
+  #     include Pundit::Authorization
+  #   end
+  # @see #pundit
+  # @api public
   module Authorization
     extend ActiveSupport::Concern
 
@@ -15,7 +23,13 @@ module Pundit
 
     protected
 
-    # @return [Pundit::Context] a new instance of {Pundit::Context} with the current user
+    # An instance of {Pundit::Context} initialized with the current user.
+    #
+    # @note this method is memoized and will return the same instance during the request.
+    # @api public
+    # @return [Pundit::Context]
+    # @see #pundit_user
+    # @see #policies
     def pundit
       @pundit ||= Pundit::Context.new(
         user: pundit_user,
@@ -23,40 +37,38 @@ module Pundit
       )
     end
 
-    # @return [Boolean] whether authorization has been performed, i.e. whether
-    #                   one {#authorize} or {#skip_authorization} has been called
-    def pundit_policy_authorized?
-      !!@_pundit_policy_authorized
-    end
-
-    # @return [Boolean] whether policy scoping has been performed, i.e. whether
-    #                   one {#policy_scope} or {#skip_policy_scope} has been called
-    def pundit_policy_scoped?
-      !!@_pundit_policy_scoped
-    end
-
-    # Raises an error if authorization has not been performed, usually used as an
-    # `after_action` filter to prevent programmer error in forgetting to call
-    # {#authorize} or {#skip_authorization}.
+    # Hook method which allows customizing which user is passed to policies and
+    # scopes initialized by {#authorize}, {#policy} and {#policy_scope}.
     #
-    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
-    # @raise [AuthorizationNotPerformedError] if authorization has not been performed
-    # @return [void]
-    def verify_authorized
-      raise AuthorizationNotPerformedError, self.class unless pundit_policy_authorized?
+    # @note Make sure to call `pundit_reset!` if this changes during a request.
+    # @see https://github.com/varvet/pundit#customize-pundit-user
+    # @see #pundit
+    # @see #pundit_reset!
+    # @return [Object] the user object to be used with pundit
+    def pundit_user
+      current_user
     end
 
-    # Raises an error if policy scoping has not been performed, usually used as an
-    # `after_action` filter to prevent programmer error in forgetting to call
-    # {#policy_scope} or {#skip_policy_scope} in index actions.
+    # Clears the cached Pundit authorization data.
+    #
+    # This method should be called when the pundit_user is changed,
+    # such as during user switching, to ensure that stale authorization
+    # data is not used. Pundit caches authorization policies and scopes
+    # for the pundit_user, so calling this method will reset those
+    # caches and ensure that the next authorization checks are performed
+    # with the correct context for the new pundit_user.
     #
-    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
-    # @raise [AuthorizationNotPerformedError] if policy scoping has not been performed
     # @return [void]
-    def verify_policy_scoped
-      raise PolicyScopingNotPerformedError, self.class unless pundit_policy_scoped?
+    def pundit_reset!
+      @pundit = nil
+      @_pundit_policies = nil
+      @_pundit_policy_scopes = nil
+      @_pundit_policy_authorized = nil
+      @_pundit_policy_scoped = nil
     end
 
+    # @!group Policies
+
     # Retrieves the policy for the given record, initializing it with the record
     # and current user and finally throwing an error if the user is not
     # authorized to perform the given action.
@@ -66,7 +78,9 @@ module Pundit
     #   If omitted then this defaults to the Rails controller action name.
     # @param policy_class [Class] the policy class we want to force use of
     # @raise [NotAuthorizedError] if the given query method returned false
-    # @return [Object] Always returns the passed object record
+    # @return [record] Always returns the passed object record
+    # @see Pundit::Context#authorize
+    # @see #verify_authorized
     def authorize(record, query = nil, policy_class: nil)
       query ||= "#{action_name}?"
 
@@ -79,29 +93,45 @@ module Pundit
     #
     # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
     # @return [void]
+    # @see #verify_authorized
     def skip_authorization
       @_pundit_policy_authorized = :skipped
     end
 
-    # Allow this action not to perform policy scoping.
+    # @return [Boolean] wether or not authorization has been performed
+    # @see #authorize
+    # @see #skip_authorization
+    def pundit_policy_authorized?
+      !!@_pundit_policy_authorized
+    end
+
+    # Raises an error if authorization has not been performed.
+    #
+    # Usually used as an `after_action` filter to prevent programmer error in
+    # forgetting to call {#authorize} or {#skip_authorization}.
     #
     # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @raise [AuthorizationNotPerformedError] if authorization has not been performed
     # @return [void]
-    def skip_policy_scope
-      @_pundit_policy_scoped = :skipped
+    # @see #authorize
+    # @see #skip_authorization
+    def verify_authorized
+      raise AuthorizationNotPerformedError, self.class unless pundit_policy_authorized?
     end
 
-    # Retrieves the policy scope for the given record.
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+
+    # Cache of policies. You should not rely on this method.
     #
-    # @see https://github.com/varvet/pundit#scopes
-    # @param scope [Object] the object we're retrieving the policy scope for
-    # @param policy_scope_class [Class] the policy scope class we want to force use of
-    # @return [Scope{#resolve}, nil] instance of scope class which can resolve to a scope
-    def policy_scope(scope, policy_scope_class: nil)
-      @_pundit_policy_scoped = true
-      policy_scope_class ? policy_scope_class.new(pundit_user, scope).resolve : pundit_policy_scope(scope)
+    # @api private
+    def policies
+      @_pundit_policies ||= {}
     end
 
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    # @!endgroup
+
     # Retrieves the policy for the given record.
     #
     # @see https://github.com/varvet/pundit#policies
@@ -111,11 +141,87 @@ module Pundit
       pundit.policy!(record)
     end
 
-    # Retrieves a set of permitted attributes from the policy by instantiating
-    # the policy class for the given record and calling `permitted_attributes` on
-    # it, or `permitted_attributes_for_{action}` if `action` is defined. It then infers
-    # what key the record should have in the params hash and retrieves the
-    # permitted attributes from the params hash under that key.
+    # @!group Policy Scopes
+
+    # Retrieves the policy scope for the given record.
+    #
+    # @see https://github.com/varvet/pundit#scopes
+    # @param scope [Object] the object we're retrieving the policy scope for
+    # @param policy_scope_class [#resolve] the policy scope class we want to force use of
+    # @return [#resolve, nil] instance of scope class which can resolve to a scope
+    def policy_scope(scope, policy_scope_class: nil)
+      @_pundit_policy_scoped = true
+      policy_scope_class ? policy_scope_class.new(pundit_user, scope).resolve : pundit_policy_scope(scope)
+    end
+
+    # Allow this action not to perform policy scoping.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @return [void]
+    # @see #verify_policy_scoped
+    def skip_policy_scope
+      @_pundit_policy_scoped = :skipped
+    end
+
+    # @return [Boolean] wether or not policy scoping has been performed
+    # @see #policy_scope
+    # @see #skip_policy_scope
+    def pundit_policy_scoped?
+      !!@_pundit_policy_scoped
+    end
+
+    # Raises an error if policy scoping has not been performed.
+    #
+    # Usually used as an `after_action` filter to prevent programmer error in
+    # forgetting to call {#policy_scope} or {#skip_policy_scope} in index
+    # actions.
+    #
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @raise [AuthorizationNotPerformedError] if policy scoping has not been performed
+    # @return [void]
+    # @see #policy_scope
+    # @see #skip_policy_scope
+    def verify_policy_scoped
+      raise PolicyScopingNotPerformedError, self.class unless pundit_policy_scoped?
+    end
+
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+
+    # Cache of policy scope. You should not rely on this method.
+    #
+    # @api private
+    def policy_scopes
+      @_pundit_policy_scopes ||= {}
+    end
+
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    # This was added to allow calling `policy_scope!` without flipping the
+    # `pundit_policy_scoped?` flag.
+    #
+    # It's used internally by `policy_scope`, as well as from the views
+    # when they call `policy_scope`. It works because views get their helper
+    # from {Pundit::Helper}.
+    #
+    # @note This also memoizes the instance with `scope` as the key.
+    # @see Pundit::Helper#policy_scope
+    # @api private
+    def pundit_policy_scope(scope)
+      policy_scopes[scope] ||= pundit.policy_scope!(scope)
+    end
+    private :pundit_policy_scope
+
+    # @!endgroup
+
+    # @!group Strong Parameters
+
+    # Retrieves a set of permitted attributes from the policy.
+    #
+    # Done by instantiating the policy class for the given record and calling
+    # `permitted_attributes` on it, or `permitted_attributes_for_{action}` if
+    # `action` is defined. It then infers what key the record should have in the
+    # params hash and retrieves the permitted attributes from the params hash
+    # under that key.
     #
     # @see https://github.com/varvet/pundit#strong-parameters
     # @param record [Object] the object we're retrieving permitted attributes for
@@ -140,37 +246,6 @@ module Pundit
       params.require(PolicyFinder.new(record).param_key)
     end
 
-    # Cache of policies. You should not rely on this method.
-    #
-    # @api private
-    # rubocop:disable Naming/MemoizedInstanceVariableName
-    def policies
-      @_pundit_policies ||= {}
-    end
-    # rubocop:enable Naming/MemoizedInstanceVariableName
-
-    # Cache of policy scope. You should not rely on this method.
-    #
-    # @api private
-    # rubocop:disable Naming/MemoizedInstanceVariableName
-    def policy_scopes
-      @_pundit_policy_scopes ||= {}
-    end
-    # rubocop:enable Naming/MemoizedInstanceVariableName
-
-    # Hook method which allows customizing which user is passed to policies and
-    # scopes initialized by {#authorize}, {#policy} and {#policy_scope}.
-    #
-    # @see https://github.com/varvet/pundit#customize-pundit-user
-    # @return [Object] the user object to be used with pundit
-    def pundit_user
-      current_user
-    end
-
-    private
-
-    def pundit_policy_scope(scope)
-      policy_scopes[scope] ||= pundit.policy_scope!(scope)
-    end
+    # @!endgroup
   end
 end

data/lib/pundit/cache_store/legacy_store.rb

@@ -2,12 +2,19 @@
 
 module Pundit
   module CacheStore
+    # A cache store that uses only the record as a cache key, and ignores the user.
+    #
+    # The original cache mechanism used by Pundit.
+    #
     # @api private
     class LegacyStore
       def initialize(hash = {})
         @store = hash
       end
 
+      # A cache store that uses only the record as a cache key, and ignores the user.
+      #
+      # @note `nil` results are not cached.
       def fetch(user:, record:)
         _ = user
         @store[record] ||= yield

data/lib/pundit/cache_store/null_store.rb

@@ -2,14 +2,23 @@
 
 module Pundit
   module CacheStore
+    # A cache store that does not cache anything.
+    #
+    # Use `NullStore.instance` to get the singleton instance, it is thread-safe.
+    #
+    # @see Pundit::Context#initialize
     # @api private
     class NullStore
       @instance = new
 
       class << self
+        # @return [NullStore] the singleton instance
         attr_reader :instance
       end
 
+      # Always yields, does not cache anything.
+      # @yield
+      # @return [any] whatever the block returns.
       def fetch(*, **)
         yield
       end

data/lib/pundit/cache_store.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Pundit
+  # Namespace for cache store implementations.
+  #
+  # Cache stores are used to cache policy lookups, so you get the same policy
+  # instance for the same record.
+  module CacheStore
+    # @!group Cache Store Interface
+
+    # @!method fetch(user:, record:, &block)
+    #   Looks up a stored policy or generate a new one.
+    #
+    #   @note This is a method template, but the method does not exist in this module.
+    #   @param user [Object]  the user that initiated the action
+    #   @param record [Object] the object being accessed
+    #   @param block [Proc] the block to execute if missing
+    #   @return [Object] the policy
+
+    # @!endgroup
+  end
+end

data/lib/pundit/context.rb

@@ -1,22 +1,53 @@
 # frozen_string_literal: true
 
 module Pundit
+  # {Pundit::Context} is intended to be created once per request and user, and
+  # it is then used to perform authorization checks throughout the request.
+  #
+  # @example Using Sinatra
+  #   helpers do
+  #     def current_user = ...
+  #
+  #     def pundit
+  #       @pundit ||= Pundit::Context.new(user: current_user)
+  #     end
+  #   end
+  #
+  #   get "/posts/:id" do |id|
+  #     pundit.authorize(Post.find(id), query: :show?)
+  #   end
+  #
+  # @example Using [Roda](https://roda.jeremyevans.net/index.html)
+  #   route do |r|
+  #     context = Pundit::Context.new(user:)
+  #
+  #     r.get "posts", Integer do |id|
+  #       context.authorize(Post.find(id), query: :show?)
+  #     end
+  #   end
   class Context
+    # @see Pundit::Authorization#pundit
+    # @param user later passed to policies and scopes
+    # @param policy_cache [#fetch] cache store for policies (see e.g. {CacheStore::NullStore})
     def initialize(user:, policy_cache: CacheStore::NullStore.instance)
       @user = user
       @policy_cache = policy_cache
     end
 
+    # @api public
+    # @see #initialize
     attr_reader :user
 
     # @api private
+    # @see #initialize
     attr_reader :policy_cache
 
+    # @!group Policies
+
     # Retrieves the policy for the given record, initializing it with the
     # record and user and finally throwing an error if the user is not
     # authorized to perform the given action.
     #
-    # @param user [Object] the user that initiated the action
     # @param possibly_namespaced_record [Object, Array] the object we're checking permissions of
     # @param query [Symbol, String] the predicate method to check on the policy (e.g. `:show?`)
     # @param policy_class [Class] the policy class we want to force use of
@@ -35,10 +66,34 @@ module Pundit
       record
     end
 
+    # Retrieves the policy for the given record.
+    #
+    # @see https://github.com/varvet/pundit#policies
+    # @param record [Object] the object we're retrieving the policy for
+    # @raise [InvalidConstructorError] if the policy constructor called incorrectly
+    # @return [Object, nil] instance of policy class with query methods
+    def policy(record)
+      cached_find(record, &:policy)
+    end
+
+    # Retrieves the policy for the given record, or raises if not found.
+    #
+    # @see https://github.com/varvet/pundit#policies
+    # @param record [Object] the object we're retrieving the policy for
+    # @raise [NotDefinedError] if the policy cannot be found
+    # @raise [InvalidConstructorError] if the policy constructor called incorrectly
+    # @return [Object] instance of policy class with query methods
+    def policy!(record)
+      cached_find(record, &:policy!)
+    end
+
+    # @!endgroup
+
+    # @!group Scopes
+
     # Retrieves the policy scope for the given record.
     #
     # @see https://github.com/varvet/pundit#scopes
-    # @param user [Object] the user that initiated the action
     # @param scope [Object] the object we're retrieving the policy scope for
     # @raise [InvalidConstructorError] if the policy constructor called incorrectly
     # @return [Scope{#resolve}, nil] instance of scope class which can resolve to a scope
@@ -58,14 +113,12 @@ module Pundit
     # Retrieves the policy scope for the given record. Raises if not found.
     #
     # @see https://github.com/varvet/pundit#scopes
-    # @param user [Object] the user that initiated the action
     # @param scope [Object] the object we're retrieving the policy scope for
     # @raise [NotDefinedError] if the policy scope cannot be found
     # @raise [InvalidConstructorError] if the policy constructor called incorrectly
     # @return [Scope{#resolve}] instance of scope class which can resolve to a scope
     def policy_scope!(scope)
       policy_scope_class = policy_finder(scope).scope!
-      return unless policy_scope_class
 
       begin
         policy_scope = policy_scope_class.new(user, pundit_model(scope))
@@ -76,31 +129,21 @@ module Pundit
       policy_scope.resolve
     end
 
-    # Retrieves the policy for the given record.
-    #
-    # @see https://github.com/varvet/pundit#policies
-    # @param user [Object] the user that initiated the action
-    # @param record [Object] the object we're retrieving the policy for
-    # @raise [InvalidConstructorError] if the policy constructor called incorrectly
-    # @return [Object, nil] instance of policy class with query methods
-    def policy(record)
-      cached_find(record, &:policy)
-    end
-
-    # Retrieves the policy for the given record. Raises if not found.
-    #
-    # @see https://github.com/varvet/pundit#policies
-    # @param user [Object] the user that initiated the action
-    # @param record [Object] the object we're retrieving the policy for
-    # @raise [NotDefinedError] if the policy cannot be found
-    # @raise [InvalidConstructorError] if the policy constructor called incorrectly
-    # @return [Object] instance of policy class with query methods
-    def policy!(record)
-      cached_find(record, &:policy!)
-    end
+    # @!endgroup
 
     private
 
+    # @!group Private Helpers
+
+    # Finds a cached policy for the given record, or yields to find one.
+    #
+    # @api private
+    # @param record [Object] the object we're retrieving the policy for
+    # @yield a policy finder if no policy was cached
+    # @yieldparam [PolicyFinder] policy_finder
+    # @yieldreturn [#new(user, model)]
+    # @return [Policy, nil] an instantiated policy
+    # @raise [InvalidConstructorError] if policy can't be instantated
     def cached_find(record)
       policy_cache.fetch(user: user, record: record) do
         klass = yield policy_finder(record)
@@ -116,10 +159,17 @@ module Pundit
       end
     end
 
+    # Return a policy finder for the given record.
+    #
+    # @api private
+    # @return [PolicyFinder]
     def policy_finder(record)
       PolicyFinder.new(record)
     end
 
+    # Given a possibly namespaced record, return the actual record.
+    #
+    # @api private
     def pundit_model(record)
       record.is_a?(Array) ? record.last : record
     end

data/lib/pundit/policy_finder.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# String#safe_constantize, String#demodulize, String#underscore, String#camelize
+require "active_support/core_ext/string/inflections"
+
 module Pundit
   # Finds policy and scope classes for given object.
   # @api public
@@ -10,10 +13,15 @@ module Pundit
   #   finder.scope #=> UserPolicy::Scope
   #
   class PolicyFinder
+    # A constant applied to the end of the class name to find the policy class.
+    #
+    # @api private
+    SUFFIX = "Policy"
+
+    # @see #initialize
     attr_reader :object
 
     # @param object [any] the object to find policy and scope classes for
-    #
     def initialize(object)
       @object = object
     end
@@ -70,6 +78,11 @@ module Pundit
 
     private
 
+    # Given an object, find the policy class name.
+    #
+    # Uses recursion to handle namespaces.
+    #
+    # @return [String, Class] the policy class, or its name.
     def find(subject)
       if subject.is_a?(Array)
         modules = subject.dup
@@ -86,6 +99,14 @@ module Pundit
       end
     end
 
+    # Given an object, find its' class name.
+    #
+    # - Supports ActiveModel.
+    # - Supports regular classes.
+    # - Supports symbols.
+    # - Supports object instances.
+    #
+    # @return [String, Class] the class, or its name.
     def find_class_name(subject)
       if subject.respond_to?(:model_name)
         subject.model_name

data/lib/pundit/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Pundit
+  class Railtie < Rails::Railtie
+    if Rails.version.to_f >= 8.0
+      initializer "pundit.stats_directories" do
+        require "rails/code_statistics"
+
+        if Rails.root.join("app/policies").directory?
+          Rails::CodeStatistics.register_directory("Policies", "app/policies")
+        end
+
+        if Rails.root.join("test/policies").directory?
+          Rails::CodeStatistics.register_directory("Policy tests", "test/policies", test_directory: true)
+        end
+      end
+    end
+  end
+end