pundit 2.2.0 → 2.5.2

data/lib/generators/rspec/policy_generator.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
+# @private
 module Rspec
+  # @private
   module Generators
+    # @private
     class PolicyGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_policy_spec
-        template "policy_spec.rb", File.join("spec/policies", class_path, "#{file_name}_policy_spec.rb")
+        template "policy_spec.rb.tt", File.join("spec/policies", class_path, "#{file_name}_policy_spec.rb")
       end
     end
   end

data/lib/generators/rspec/templates/{policy_spec.rb → policy_spec.rb.tt}

@@ -1,4 +1,4 @@
-require '<%= File.exists?('spec/rails_helper.rb') ? 'rails_helper' : 'spec_helper' %>'
+require '<%= File.exist?('spec/rails_helper.rb') ? 'rails_helper' : 'spec_helper' %>'
 
 RSpec.describe <%= class_name %>Policy, type: :policy do
   let(:user) { User.new }

data/lib/generators/test_unit/policy_generator.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
+# @private
 module TestUnit
+  # @private
   module Generators
+    # @private
     class PolicyGenerator < ::Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 
       def create_policy_test
-        template "policy_test.rb", File.join("test/policies", class_path, "#{file_name}_policy_test.rb")
+        template "policy_test.rb.tt", File.join("test/policies", class_path, "#{file_name}_policy_test.rb")
       end
     end
   end

data/lib/pundit/authorization.rb

@@ -1,6 +1,15 @@
 # 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
+  # @since v2.2.0
   module Authorization
     extend ActiveSupport::Concern
 
@@ -15,40 +24,55 @@ module Pundit
 
     protected
 
-    # @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
+    # 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
+    # @since v2.3.2
+    def pundit
+      @pundit ||= Pundit::Context.new(
+        user: pundit_user,
+        policy_cache: Pundit::CacheStore::LegacyStore.new(policies)
+      )
     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
+    # @since v0.2.2
+    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?
+    # @since v2.5.0
+    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.
@@ -58,62 +82,169 @@ 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
+    # @since v0.1.0
     def authorize(record, query = nil, policy_class: nil)
       query ||= "#{action_name}?"
 
       @_pundit_policy_authorized = true
 
-      Pundit.authorize(pundit_user, record, query, policy_class: policy_class, cache: policies)
+      pundit.authorize(record, query: query, policy_class: policy_class)
     end
 
     # Allow this action not to perform authorization.
     #
     # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
     # @return [void]
+    # @see #verify_authorized
+    # @since v1.0.0
     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
+    # @since v1.0.0
+    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
+    # @since v0.1.0
+    def verify_authorized
+      raise AuthorizationNotPerformedError, self.class unless pundit_policy_authorized?
+    end
+
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+
+    # Cache of policies. You should not rely on this method.
+    #
+    # @api private
+    # @since v1.0.0
+    def policies
+      @_pundit_policies ||= {}
+    end
+
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    # @!endgroup
+
+    # 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
+    # @return [Object] instance of policy class with query methods
+    # @since v0.1.0
+    def policy(record)
+      pundit.policy!(record)
     end
 
+    # @!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 [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
+    # @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
+    # @since v0.1.0
     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
 
-    # Retrieves the policy for the given record.
+    # Allow this action not to perform policy scoping.
     #
-    # @see https://github.com/varvet/pundit#policies
-    # @param record [Object] the object we're retrieving the policy for
-    # @return [Object, nil] instance of policy class with query methods
-    def policy(record)
-      policies[record] ||= Pundit.policy!(pundit_user, record)
+    # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
+    # @return [void]
+    # @see #verify_policy_scoped
+    # @since v1.0.0
+    def skip_policy_scope
+      @_pundit_policy_scoped = :skipped
     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.
+    # @return [Boolean] wether or not policy scoping has been performed
+    # @see #policy_scope
+    # @see #skip_policy_scope
+    # @since v1.0.0
+    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
+    # @since v0.2.1
+    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
+    # @since v1.0.0
+    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
+    # @since v1.0.0
+    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
     # @param action [Symbol, String] the name of the action being performed on the record (e.g. `:update`).
     #   If omitted then this defaults to the Rails controller action name.
     # @return [Hash{String => Object}] the permitted attributes
+    # @since v1.0.0
     def permitted_attributes(record, action = action_name)
       policy = policy(record)
       method_name = if policy.respond_to?("permitted_attributes_for_#{action}")
@@ -128,41 +259,11 @@ module Pundit
     #
     # @param record [Object] the object we're retrieving params for
     # @return [ActionController::Parameters] the params
+    # @since v2.0.0
     def pundit_params_for(record)
       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!(pundit_user, scope)
-    end
+    # @!endgroup
   end
 end

data/lib/pundit/cache_store/legacy_store.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+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
+    # @since v2.3.2
+    class LegacyStore
+      # @since v2.3.2
+      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.
+      # @since v2.3.2
+      def fetch(user:, record:)
+        _ = user
+        @store[record] ||= yield
+      end
+    end
+  end
+end

data/lib/pundit/cache_store/null_store.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+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
+    # @since v2.3.2
+    class NullStore
+      @instance = new
+
+      class << self
+        # @since v2.3.2
+        # @return [NullStore] the singleton instance
+        attr_reader :instance
+      end
+
+      # Always yields, does not cache anything.
+      # @yield
+      # @return [any] whatever the block returns.
+      # @since v2.3.2
+      def fetch(*, **)
+        yield
+      end
+    end
+  end
+end

data/lib/pundit/cache_store.rb

@@ -0,0 +1,24 @@
+# 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.
+  # @since v2.3.2
+  module CacheStore
+    # @!group Cache Store Interface
+
+    # @!method fetch(user:, record:, &block)
+    #   Looks up a stored policy or generate a new one.
+    #
+    #   @since v2.3.2
+    #   @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

@@ -0,0 +1,190 @@
+# 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
+  #
+  # @since v2.3.2
+  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})
+    # @since v2.3.2
+    def initialize(user:, policy_cache: CacheStore::NullStore.instance)
+      @user = user
+      @policy_cache = policy_cache
+    end
+
+    # @api public
+    # @see #initialize
+    # @since v2.3.2
+    attr_reader :user
+
+    # @api private
+    # @see #initialize
+    # @since v2.3.2
+    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 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
+    # @raise [NotAuthorizedError] if the given query method returned false
+    # @return [Object] Always returns the passed object record
+    # @since v2.3.2
+    def authorize(possibly_namespaced_record, query:, policy_class:)
+      record = pundit_model(possibly_namespaced_record)
+      policy = if policy_class
+        policy_class.new(user, record)
+      else
+        policy!(possibly_namespaced_record)
+      end
+
+      raise NotAuthorizedError, query: query, record: record, policy: policy unless policy.public_send(query)
+
+      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
+    # @since v2.3.2
+    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
+    # @since v2.3.2
+    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 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
+    # @since v2.3.2
+    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))
+      rescue ArgumentError
+        raise InvalidConstructorError, "Invalid #<#{policy_scope_class}> constructor is called"
+      end
+
+      policy_scope.resolve
+    end
+
+    # Retrieves the policy scope for the given record. Raises if not found.
+    #
+    # @see https://github.com/varvet/pundit#scopes
+    # @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
+    # @since v2.3.2
+    def policy_scope!(scope)
+      policy_scope_class = policy_finder(scope).scope!
+
+      begin
+        policy_scope = policy_scope_class.new(user, pundit_model(scope))
+      rescue ArgumentError
+        raise InvalidConstructorError, "Invalid #<#{policy_scope_class}> constructor is called"
+      end
+
+      policy_scope.resolve
+    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
+    # @since v2.3.2
+    def cached_find(record)
+      policy_cache.fetch(user: user, record: record) do
+        klass = yield policy_finder(record)
+        next unless klass
+
+        model = pundit_model(record)
+
+        begin
+          klass.new(user, model)
+        rescue ArgumentError
+          raise InvalidConstructorError, "Invalid #<#{klass}> constructor is called"
+        end
+      end
+    end
+
+    # Return a policy finder for the given record.
+    #
+    # @api private
+    # @return [PolicyFinder]
+    # @since v2.3.2
+    def policy_finder(record)
+      PolicyFinder.new(record)
+    end
+
+    # Given a possibly namespaced record, return the actual record.
+    #
+    # @api private
+    # @since v2.3.2
+    def pundit_model(record)
+      record.is_a?(Array) ? record.last : record
+    end
+  end
+end