action_policy 0.0.1 → 0.1.0

data/docs/writing_policies.md

@@ -0,0 +1,55 @@
+# Writing Policies
+
+Policy class contains predicate methods (_rules_) which are used to authorize activities.
+
+A Policy is instantiated with the target `record` (authorization object) and the [authorization context](authorization_context.md) (by default equals to `user`):
+
+```ruby
+class PostPolicy < ActionPolicy::Base
+  def index?
+    # allow everyone to perform "index" activity on posts
+    true
+  end
+
+  def update?
+    # here we can access our context and record
+    user.admin? || (user.id == record.user_id)
+  end
+end
+```
+
+## Initializing policies
+
+**NOTE**: it is not recommended to manually initialize policy objects and use them directly (one exclusion–[tests](testing.md)). Use `authorize!` / `allowed_to?` methods instead.
+
+To initialize policy object, you should specify target record and context:
+
+```ruby
+policy = PostPolicy.new(post, user: user)
+
+# simply call rule method
+policy.update?
+```
+
+You can omit the first argument (in that case `record` would be `nil`).
+
+Instead of calling rules directly, it is better to call the `apply` method (which wraps rule method with some useful functionality, such as [caching](caching.md), [pre-checks](pre_checks.md), and [failure reasons tracking](reasons.md)):
+
+```ruby
+policy.apply(:update?)
+```
+
+## Calling other policies
+
+Sometimes it is useful to call other resources policies from within a policy. Action Policy provides the `allowed_to?` method as a part of `ActionPolicy::Base`:
+
+```ruby
+class CommentPolicy < ApplicationPolicy
+  def update?
+    user.admin? || (user.id == record.id) ||
+      allowed_to?(:update?, record.post)
+  end
+end
+```
+
+You can also specify all the usual options (such as `with`).

data/gemfiles/jruby.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gem "rails", "~> 5.0"
+
+gemspec path: ".."

data/gemfiles/rails42.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gem "rails", "~> 4.2"
+
+gemspec path: ".."

data/gemfiles/railsmaster.gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gem "arel", github: "rails/arel"
+gem "rails", github: "rails/rails"
+
+gemspec path: ".."

data/lib/action_policy.rb

@@ -1,5 +1,37 @@
-require "action_policy/version"
+# frozen_string_literal: true
 
+# ActionPolicy is an authorization framework for Ruby/Rails applications.
+#
+# It provides a way to write access policies and helpers to check these policies
+# in your application.
 module ActionPolicy
-  # Your code goes here...
+  class Error < StandardError; end
+
+  # Raised when Action Policy fails to find a policy class for a record.
+  class NotFound < Error
+    attr_reader :target, :message
+
+    def initialize(target)
+      @target = target
+      @message = "Couldn't find policy class for #{target.inspect}"
+    end
+  end
+
+  require "action_policy/version"
+  require "action_policy/base"
+  require "action_policy/lookup_chain"
+  require "action_policy/authorizer"
+  require "action_policy/behaviour"
+
+  class << self
+    attr_accessor :cache_store
+
+    # Find a policy class for a target
+    def lookup(target, **options)
+      LookupChain.call(target, **options) ||
+        raise(NotFound, target)
+    end
+  end
+
+  require "action_policy/railtie" if defined?(::Rails)
 end

data/lib/action_policy/authorizer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  # Raised when `authorize!` check fails
+  class Unauthorized < Error
+    attr_reader :policy, :rule, :reasons
+
+    def initialize(policy, rule)
+      @policy = policy.class
+      @rule = rule
+      # Reasons module could be not included
+      @reasons = policy.reasons if policy.respond_to?(:reasons)
+    end
+  end
+
+  # Performs authorization, raises an exception when check failed.
+  #
+  # The main purpose of this module is to extact authorize action
+  # from everything else to make it easily testable.
+  module Authorizer
+    class << self
+      def call(policy, rule)
+        policy.apply(rule) ||
+          raise(::ActionPolicy::Unauthorized.new(policy, rule))
+      end
+    end
+  end
+end

data/lib/action_policy/base.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  # Base class for application policies.
+  class Base
+    require "action_policy/policy/core"
+    require "action_policy/policy/defaults"
+    require "action_policy/policy/authorization"
+    require "action_policy/policy/reasons"
+    require "action_policy/policy/pre_check"
+    require "action_policy/policy/aliases"
+    require "action_policy/policy/cache"
+    require "action_policy/policy/cached_apply"
+
+    include ActionPolicy::Policy::Core
+    include ActionPolicy::Policy::Authorization
+    include ActionPolicy::Policy::Reasons
+    include ActionPolicy::Policy::PreCheck
+    include ActionPolicy::Policy::Aliases
+    include ActionPolicy::Policy::Cache
+    include ActionPolicy::Policy::CachedApply
+    include ActionPolicy::Policy::Defaults
+  end
+end

data/lib/action_policy/behaviour.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "action_policy/behaviours/policy_for"
+require "action_policy/behaviours/memoized"
+require "action_policy/behaviours/thread_memoized"
+require "action_policy/behaviours/namespaced"
+
+module ActionPolicy
+  # Provides `authorize!` and `allowed_to?` methods and
+  # `authorize` class method to define authorization context.
+  #
+  # Could be included anywhere to perform authorization.
+  module Behaviour
+    include ActionPolicy::Behaviours::PolicyFor
+
+    def self.included(base)
+      # Handle ActiveSupport::Concern differently
+      if base.respond_to?(:class_methods)
+        base.class_methods do
+          include ClassMethods
+        end
+      else
+        base.extend ClassMethods
+      end
+    end
+
+    # Authorize action against a policy.
+    #
+    # Policy is inferred from record
+    # (unless explicitly specified through `with` option).
+    #
+    # Raises `ActionPolicy::Unauthorized` if check failed.
+    def authorize!(record, to:, **options)
+      policy = policy_for(record: record, **options)
+
+      Authorizer.call(policy, authorization_rule_for(policy, to))
+    end
+
+    # Checks that an activity is allowed for the current context (e.g. user).
+    #
+    # Returns true of false.
+    def allowed_to?(rule, record, **options)
+      policy = policy_for(record: record, **options)
+      policy.apply(authorization_rule_for(policy, rule))
+    end
+
+    def authorization_context
+      return @__authorization_context if
+        instance_variable_defined?(:@__authorization_context)
+
+      @__authorization_context = self.class.authorization_targets
+                                     .each_with_object({}) do |(key, meth), obj|
+        obj[key] = public_send(meth)
+      end
+    end
+
+    # Check that rule is defined for policy,
+    # otherwise fallback to :manage? rule.
+    def authorization_rule_for(policy, rule)
+      policy.resolve_rule(rule)
+    end
+
+    module ClassMethods # :nodoc:
+      # Configure authorization context.
+      #
+      # For example:
+      #
+      #   class ApplicationController < ActionController::Base
+      #     # Pass the value of `current_user` to authorization as `user`
+      #     authorize :user, through: :current_user
+      #   end
+      #
+      #   # Assuming that in your ApplicationPolicy
+      #   class ApplicationPolicy < ActionPolicy::Base
+      #     authorize :user
+      #   end
+      def authorize(key, through: nil)
+        meth = through || key
+        authorization_targets[key] = meth
+      end
+
+      def authorization_targets
+        return @authorization_targets if instance_variable_defined?(:@authorization_targets)
+
+        @authorization_targets =
+          if superclass.respond_to?(:authorization_targets)
+            superclass.authorization_targets.dup
+          else
+            {}
+          end
+      end
+    end
+  end
+end

data/lib/action_policy/behaviours/memoized.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  module Behaviours
+    # Per-instance memoization for policies.
+    #
+    # Used by `policy_for` to re-use policy object for records.
+    #
+    # Example:
+    #
+    #   include ActionPolicy::Behaviour
+    #   include ActionPolicy::Memoized
+    #
+    #   record = User.first
+    #   policy = policy_for(record)
+    #   policy2 = policy_for(record)
+    #
+    #   policy.equal?(policy) #=> true
+    #
+    #   policy.equal?(policy_for(record, with: CustomPolicy)) #=> false
+    module Memoized
+      require "action_policy/ext/policy_cache_key"
+      using ActionPolicy::Ext::PolicyCacheKey
+
+      class << self
+        def prepended(base)
+          base.prepend InstanceMethods
+        end
+
+        alias included prepended
+      end
+
+      module InstanceMethods # :nodoc:
+        def policy_for(record:, **opts)
+          __policy_memoize__(record, **opts) { super(record: record, **opts) }
+        end
+      end
+
+      def __policy_memoize__(record, with: nil, namespace: nil)
+        record_key = record._policy_cache_key(use_object_id: true)
+        cache_key = "#{namespace}/#{with}/#{record_key}"
+
+        return __policies_cache__[cache_key] if
+          __policies_cache__.key?(cache_key)
+
+        policy = yield
+
+        __policies_cache__[cache_key] = policy
+      end
+
+      def __policies_cache__
+        @__policies_cache__ ||= {}
+      end
+    end
+  end
+end

data/lib/action_policy/behaviours/namespaced.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  module Behaviours
+    # Adds an ability to lookup policies from current _context_ (namespace):
+    #
+    #   module Admin
+    #     class UsersController < ApplictionController
+    #       def index
+    #         # uses Admin::UserPolicy if any, otherwise fallbacks to UserPolicy
+    #         authorize!
+    #       end
+    #     end
+    #   end
+    #
+    # Modules nesting is also supported:
+    #
+    #   module Admin
+    #     module Client
+    #       class UsersController < ApplictionController
+    #         def index
+    #           # lookup for Admin::Client::UserPolicy -> Admin::UserPolicy -> UserPolicy
+    #           authorize!
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # NOTE: in order to support namespaced lookup for non-inferrable resources,
+    # you should specify `policy_name` at a class level
+    # (instead of `policy_class`, which doesn't take into account namespaces):
+    #
+    #  class Guest < User
+    #     def self.policy_name
+    #       "UserPolicy"
+    #     end
+    #  end
+    #
+    # NOTE: by default, we use class's name as a policy name; so, for namespaced
+    # resources the namespace part is also included:
+    #
+    #  class Admin
+    #    class User
+    #    end
+    #  end
+    #
+    #  # search for Admin::UserPolicy, but not for UserPolicy
+    #  authorize! Admin::User.new
+    #
+    # You can access the current authorization namespace through `authorization_namespace` method.
+    #
+    # You can also define your own namespacing logic by overriding `authorization_namespace`:
+    #
+    #   def authorization_namespace
+    #     return ::Admin if current_user.admin?
+    #     return ::Staff if current_user.staff?
+    #     # fallback to current namespace
+    #     super
+    #   end
+    module Namespaced
+      require "action_policy/ext/module_namespace"
+      using ActionPolicy::Ext::ModuleNamespace
+
+      class << self
+        def prepended(base)
+          base.prepend InstanceMethods
+        end
+
+        alias included prepended
+      end
+
+      module InstanceMethods # :nodoc:
+        def authorization_namespace
+          return @authorization_namespace if instance_variable_defined?(:@authorization_namespace)
+          @authorization_namespace = self.class.namespace
+        end
+      end
+    end
+  end
+end

data/lib/action_policy/behaviours/policy_for.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  module Behaviours
+    # Adds `policy_for` method
+    module PolicyFor
+      # Returns policy instance for the record.
+      def policy_for(record:, with: nil, namespace: nil)
+        namespace ||= authorization_namespace
+        policy_class = with || ::ActionPolicy.lookup(record, namespace: namespace)
+        policy_class.new(record, **authorization_context)
+      end
+
+      def authorization_context
+        raise NotImplementedError, "Please, define `authorization_context` method!"
+      end
+
+      def authorization_namespace
+        # override to provide specific authorization namespace
+      end
+    end
+  end
+end

data/lib/action_policy/behaviours/thread_memoized.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActionPolicy
+  module PerThreadCache # :nodoc:
+    CACHE_KEY = "action_policy.per_thread_cache"
+
+    class << self
+      def fetch(key)
+        store = (Thread.current[CACHE_KEY] ||= {})
+
+        return store[key] if store.key?(key)
+
+        store[key] = yield
+      end
+
+      def clear_all
+        Thread.current[CACHE_KEY] = {}
+      end
+    end
+  end
+
+  module Behaviours
+    # Per-thread memoization for policies.
+    #
+    # Used by `policy_for` to re-use policy object for records.
+    #
+    # NOTE: don't forget to clear thread cache with ActionPolicy::PerThreadCache.clear_all
+    module ThreadMemoized
+      require "action_policy/ext/policy_cache_key"
+      using ActionPolicy::Ext::PolicyCacheKey
+
+      class << self
+        def prepended(base)
+          base.prepend InstanceMethods
+        end
+
+        alias included prepended
+      end
+
+      module InstanceMethods # :nodoc:
+        def policy_for(record:, **opts)
+          __policy_thread_memoize__(record, **opts) { super(record: record, **opts) }
+        end
+      end
+
+      def __policy_thread_memoize__(record, with: nil, namespace: nil)
+        record_key = record._policy_cache_key(use_object_id: true)
+        cache_key = "#{namespace}/#{with}/#{record_key}"
+
+        ActionPolicy::PerThreadCache.fetch(cache_key) { yield }
+      end
+    end
+  end
+end