pundit 2.1.0 → 2.5.0

data/lib/pundit/rspec.rb

@@ -1,12 +1,36 @@
 # frozen_string_literal: true
 
+# Array#to_sentence
 require "active_support/core_ext/array/conversions"
 
 module Pundit
+  # Namespace for Pundit's RSpec integration.
   module RSpec
+    # Namespace for Pundit's RSpec matchers.
     module Matchers
       extend ::RSpec::Matchers::DSL
 
+      # @!method description=(description)
+      class << self
+        # Used to build a suitable description for the Pundit `permit` matcher.
+        # @api public
+        # @param value [String, Proc]
+        # @example
+        #   Pundit::RSpec::Matchers.description = ->(user, record) do
+        #     "permit user with role #{user.role} to access record with ID #{record.id}"
+        #   end
+        attr_writer :description
+
+        # Used to retrieve a suitable description for the Pundit `permit` matcher.
+        # @api private
+        # @private
+        def description(user, record)
+          return @description.call(user, record) if defined?(@description) && @description.respond_to?(:call)
+
+          @description
+        end
+      end
+
       # rubocop:disable Metrics/BlockLength
       matcher :permit do |user, record|
         match_proc = lambda do |policy|
@@ -24,15 +48,25 @@ module Pundit
         end
 
         failure_message_proc = lambda do |policy|
-          was_were = @violating_permissions.count > 1 ? "were" : "was"
           "Expected #{policy} to grant #{permissions.to_sentence} on " \
-          "#{record} but #{@violating_permissions.to_sentence} #{was_were} not granted"
+          "#{record} but #{@violating_permissions.to_sentence} #{was_or_were} not granted"
         end
 
         failure_message_when_negated_proc = lambda do |policy|
-          was_were = @violating_permissions.count > 1 ? "were" : "was"
           "Expected #{policy} not to grant #{permissions.to_sentence} on " \
-          "#{record} but #{@violating_permissions.to_sentence} #{was_were} granted"
+          "#{record} but #{@violating_permissions.to_sentence} #{was_or_were} granted"
+        end
+
+        def was_or_were
+          if @violating_permissions.count > 1
+            "were"
+          else
+            "was"
+          end
+        end
+
+        description do
+          Pundit::RSpec::Matchers.description(user, record) || super()
         end
 
         if respond_to?(:match_when_negated)
@@ -41,26 +75,73 @@ module Pundit
           failure_message(&failure_message_proc)
           failure_message_when_negated(&failure_message_when_negated_proc)
         else
+          # :nocov:
+          # Compatibility with RSpec < 3.0, released 2014-06-01.
           match_for_should(&match_proc)
           match_for_should_not(&match_when_negated_proc)
           failure_message_for_should(&failure_message_proc)
           failure_message_for_should_not(&failure_message_when_negated_proc)
+          # :nocov:
+        end
+
+        if ::RSpec.respond_to?(:current_example)
+          def current_example
+            ::RSpec.current_example
+          end
+        else
+          # :nocov:
+          # Compatibility with RSpec < 3.0, released 2014-06-01.
+          def current_example
+            example
+          end
+          # :nocov:
         end
 
         def permissions
-          current_example = ::RSpec.respond_to?(:current_example) ? ::RSpec.current_example : example
-          current_example.metadata[:permissions]
+          current_example.metadata.fetch(:permissions) do
+            raise KeyError, <<~ERROR.strip
+              No permissions in example metadata, did you forget to wrap with `permissions :show?, ...`?
+            ERROR
+          end
         end
       end
       # rubocop:enable Metrics/BlockLength
     end
 
+    # Mixed in to all policy example groups to provide a DSL.
     module DSL
+      # @example
+      #   describe PostPolicy do
+      #     permissions :show?, :update? do
+      #       it { is_expected.to permit(user, own_post) }
+      #     end
+      #   end
+      #
+      # @example focused example group
+      #   describe PostPolicy do
+      #     permissions :show?, :update?, :focus do
+      #       it { is_expected.to permit(user, own_post) }
+      #     end
+      #   end
+      #
+      # @param list [Symbol, Array<Symbol>] a permission to describe
+      # @return [void]
       def permissions(*list, &block)
-        describe(list.to_sentence, permissions: list, caller: caller) { instance_eval(&block) }
+        metadata = { permissions: list, caller: caller }
+
+        if list.last == :focus
+          list.pop
+          metadata[:focus] = true
+        end
+
+        description = list.to_sentence
+        describe(description, metadata) { instance_eval(&block) }
       end
     end
 
+    # Mixed in to all policy example groups.
+    #
+    # @private not useful
     module PolicyExampleGroup
       include Pundit::RSpec::Matchers
 
@@ -74,17 +155,9 @@ module Pundit
 end
 
 RSpec.configure do |config|
-  if RSpec::Core::Version::STRING.split(".").first.to_i >= 3
-    config.include(
-      Pundit::RSpec::PolicyExampleGroup,
-      type: :policy,
-      file_path: %r{spec/policies}
-    )
-  else
-    config.include(
-      Pundit::RSpec::PolicyExampleGroup,
-      type: :policy,
-      example_group: { file_path: %r{spec/policies} }
-    )
-  end
+  config.include(
+    Pundit::RSpec::PolicyExampleGroup,
+    type: :policy,
+    file_path: %r{spec/policies}
+  )
 end

data/lib/pundit/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Pundit
-  VERSION = "2.1.0".freeze
+  # The current version of Pundit.
+  VERSION = "2.5.0"
 end

data/lib/pundit.rb

@@ -1,29 +1,53 @@
 # frozen_string_literal: true
 
+require "active_support"
+
 require "pundit/version"
 require "pundit/policy_finder"
-require "active_support/concern"
-require "active_support/core_ext/string/inflections"
-require "active_support/core_ext/object/blank"
-require "active_support/core_ext/module/introspection"
-require "active_support/dependencies/autoload"
+require "pundit/authorization"
+require "pundit/context"
+require "pundit/cache_store"
+require "pundit/cache_store/null_store"
+require "pundit/cache_store/legacy_store"
+require "pundit/railtie" if defined?(Rails)
 
 # @api private
 # To avoid name clashes with common Error naming when mixing in Pundit,
 # keep it here with compact class style definition.
 class Pundit::Error < StandardError; end # rubocop:disable Style/ClassAndModuleChildren
 
+# Hello? Yes, this is Pundit.
+#
 # @api public
 module Pundit
-  SUFFIX = "Policy".freeze
+  # @api private
+  # @deprecated See {Pundit::PolicyFinder}
+  SUFFIX = Pundit::PolicyFinder::SUFFIX
 
   # @api private
+  # @private
   module Generators; end
 
   # Error that will be raised when authorization has failed
   class NotAuthorizedError < Error
-    attr_reader :query, :record, :policy
-
+    # @see #initialize
+    attr_reader :query
+    # @see #initialize
+    attr_reader :record
+    # @see #initialize
+    attr_reader :policy
+
+    # @overload initialize(message)
+    #   Create an error with a simple error message.
+    #   @param [String] message A simple error message string.
+    #
+    # @overload initialize(options)
+    #   Create an error with the specified attributes.
+    #   @param [Hash] options The error options.
+    #   @option options [String] :message Optional custom error message. Will default to a generalized message.
+    #   @option options [Symbol] :query The name of the policy method that was checked.
+    #   @option options [Object] :record The object that was being checked with the policy.
+    #   @option options [Class] :policy The class of policy that was used for the check.
     def initialize(options = {})
       if options.is_a? String
         message = options
@@ -32,7 +56,10 @@ module Pundit
         @record = options[:record]
         @policy = options[:policy]
 
-        message = options.fetch(:message) { "not allowed to #{query} this #{record.class}" }
+        message = options.fetch(:message) do
+          record_name = record.is_a?(Class) ? record.to_s : "this #{record.class}"
+          "not allowed to #{policy.class}##{query} #{record_name}"
+        end
       end
 
       super(message)
@@ -53,273 +80,57 @@ module Pundit
   # Error that will be raised if a policy or policy scope is not defined.
   class NotDefinedError < Error; end
 
-  extend ActiveSupport::Concern
+  def self.included(base)
+    location = caller_locations(1, 1).first
+    warn <<~WARNING
+      'include Pundit' is deprecated. Please use 'include Pundit::Authorization' instead.
+       (called from #{location.label} at #{location.path}:#{location.lineno})
+    WARNING
+    base.include Authorization
+  end
 
   class << self
-    # 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 record [Object] 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
-    def authorize(user, record, query, policy_class: nil)
-      policy = policy_class ? policy_class.new(user, record) : policy!(user, record)
-
-      raise NotAuthorizedError, query: query, record: record, policy: policy unless policy.public_send(query)
-
-      record
-    end
-
-    # 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
-    def policy_scope(user, scope)
-      policy_scope_class = PolicyFinder.new(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"
+    # @see Pundit::Context#authorize
+    def authorize(user, record, query, policy_class: nil, cache: nil)
+      context = if cache
+        policy_cache = CacheStore::LegacyStore.new(cache)
+        Context.new(user: user, policy_cache: policy_cache)
+      else
+        Context.new(user: user)
       end
 
-      policy_scope.resolve
+      context.authorize(record, query: query, policy_class: policy_class)
     end
 
-    # 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 [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!(user, scope)
-      policy_scope_class = PolicyFinder.new(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
+    # @see Pundit::Context#policy_scope
+    def policy_scope(user, *args, **kwargs, &block)
+      Context.new(user: user).policy_scope(*args, **kwargs, &block)
     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(user, record)
-      policy = PolicyFinder.new(record).policy
-      policy.new(user, pundit_model(record)) if policy
-    rescue ArgumentError
-      raise InvalidConstructorError, "Invalid #<#{policy}> constructor is called"
+    # @see Pundit::Context#policy_scope!
+    def policy_scope!(user, *args, **kwargs, &block)
+      Context.new(user: user).policy_scope!(*args, **kwargs, &block)
     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 [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!(user, record)
-      policy = PolicyFinder.new(record).policy!
-      policy.new(user, pundit_model(record))
-    rescue ArgumentError
-      raise InvalidConstructorError, "Invalid #<#{policy}> constructor is called"
+    # @see Pundit::Context#policy
+    def policy(user, *args, **kwargs, &block)
+      Context.new(user: user).policy(*args, **kwargs, &block)
     end
 
-  private
-
-    def pundit_model(record)
-      record.is_a?(Array) ? record.last : record
+    # @see Pundit::Context#policy!
+    def policy!(user, *args, **kwargs, &block)
+      Context.new(user: user).policy!(*args, **kwargs, &block)
     end
   end
 
+  # Rails view helpers, to allow a slightly different view-specific
+  # implementation of the methods in {Pundit::Authorization}.
+  #
   # @api private
   module Helper
+    # @see Pundit::Authorization#pundit_policy_scope
     def policy_scope(scope)
       pundit_policy_scope(scope)
     end
   end
-
-  included do
-    helper Helper if respond_to?(:helper)
-    if respond_to?(:helper_method)
-      helper_method :policy
-      helper_method :pundit_policy_scope
-      helper_method :pundit_user
-    end
-  end
-
-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
-  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 verify_authorized
-    raise AuthorizationNotPerformedError, self.class unless pundit_policy_authorized?
-  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]
-  def verify_policy_scoped
-    raise PolicyScopingNotPerformedError, self.class unless pundit_policy_scoped?
-  end
-
-  # 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.
-  #
-  # @param record [Object] the object we're checking permissions of
-  # @param query [Symbol, String] the predicate method to check on the policy (e.g. `:show?`).
-  #   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
-  def authorize(record, query = nil, policy_class: nil)
-    query ||= "#{action_name}?"
-
-    @_pundit_policy_authorized = true
-
-    policy = policy_class ? policy_class.new(pundit_user, record) : policy(record)
-
-    raise NotAuthorizedError, query: query, record: record, policy: policy unless policy.public_send(query)
-
-    record
-  end
-
-  # Allow this action not to perform authorization.
-  #
-  # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
-  # @return [void]
-  def skip_authorization
-    @_pundit_policy_authorized = true
-  end
-
-  # Allow this action not to perform policy scoping.
-  #
-  # @see https://github.com/varvet/pundit#ensuring-policies-and-scopes-are-used
-  # @return [void]
-  def skip_policy_scope
-    @_pundit_policy_scoped = true
-  end
-
-  # 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
-  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.
-  #
-  # @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)
-  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.
-  #
-  # @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
-  def permitted_attributes(record, action = action_name)
-    policy = policy(record)
-    method_name = if policy.respond_to?("permitted_attributes_for_#{action}")
-      "permitted_attributes_for_#{action}"
-    else
-      "permitted_attributes"
-    end
-    pundit_params_for(record).permit(*policy.public_send(method_name))
-  end
-
-  # Retrieves the params for the given record.
-  #
-  # @param record [Object] the object we're retrieving params for
-  # @return [ActionController::Parameters] the params
-  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
 end

data/pundit.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |gem|
   gem.name          = "pundit"
   gem.version       = Pundit::VERSION
   gem.authors       = ["Jonas Nicklas", "Varvet AB"]
-  gem.email         = ["jonas.nicklas@gmail.com", "dev@elabs.se"]
+  gem.email         = ["jonas.nicklas@gmail.com", "info@varvet.com"]
   gem.description   = "Object oriented authorization for Rails applications"
   gem.summary       = "OO authorization for Rails"
   gem.homepage      = "https://github.com/varvet/pundit"
@@ -16,16 +16,16 @@ Gem::Specification.new do |gem|
 
   gem.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
   gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
-  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
+  gem.metadata      = {
+    "rubygems_mfa_required" => "true",
+    "bug_tracker_uri" => "https://github.com/varvet/pundit/issues",
+    "changelog_uri" => "https://github.com/varvet/pundit/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://github.com/varvet/pundit/blob/main/README.md",
+    "homepage_uri" => "https://github.com/varvet/pundit",
+    "source_code_uri" => "https://github.com/varvet/pundit"
+  }
+
   gem.add_dependency "activesupport", ">= 3.0.0"
-  gem.add_development_dependency "actionpack", ">= 3.0.0"
-  gem.add_development_dependency "activemodel", ">= 3.0.0"
-  gem.add_development_dependency "bundler"
-  gem.add_development_dependency "pry"
-  gem.add_development_dependency "rake"
-  gem.add_development_dependency "rspec", ">= 2.0.0"
-  gem.add_development_dependency "rubocop", "0.57.2"
-  gem.add_development_dependency "yard"
 end