action_policy 0.2.4 → 0.3.0.beta1

data/benchmarks/namespaced_lookup_cache.rb

@@ -1,17 +1,15 @@
 # frozen_string_literal: true
 
-=begin
-
-This benchmark measures the efficiency of NamespaceCache.
-
-Run it multiple times with cache on/off to see the results:
-
-  $ bundle exec ruby namespaced_lookup_cache.rb
-  $ bundle exec ruby namespaced_lookup_cache.rb
-  $ NO_CACHE=1 bundle exec ruby namespaced_lookup_cache.rb
-  $ NO_CACHE=1 bundle exec ruby namespaced_lookup_cache.rb
-
-=end
+#
+# This benchmark measures the efficiency of NamespaceCache.
+#
+# Run it multiple times with cache on/off to see the results:
+#
+#   $ bundle exec ruby namespaced_lookup_cache.rb
+#   $ bundle exec ruby namespaced_lookup_cache.rb
+#   $ NO_CACHE=1 bundle exec ruby namespaced_lookup_cache.rb
+#   $ NO_CACHE=1 bundle exec ruby namespaced_lookup_cache.rb
+#
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
@@ -37,7 +35,7 @@ end
 a = A.new
 b = B.new
 
-if ENV['NO_CACHE']
+if ENV["NO_CACHE"]
   ActionPolicy::LookupChain.namespace_cache_enabled = false
 end
 
@@ -60,16 +58,14 @@ Benchmark.ips do |x|
     ActionPolicy.lookup(b, namespace: X::Y::Z)
   end
 
-  x.hold! 'temp_results'
+  x.hold! "temp_results"
 
   x.compare!
 end
 
-=begin
-
-Comparison:
-            cache B:   178577.4 i/s
-            cache A:   173061.4 i/s - same-ish: difference falls within error
-        no cache A:    97991.7 i/s - same-ish: difference falls within error
-        no cache B:    42505.4 i/s - 4.20x  slower
-=end
+#
+# Comparison:
+#             cache B:   178577.4 i/s
+#             cache A:   173061.4 i/s - same-ish: difference falls within error
+#         no cache A:    97991.7 i/s - same-ish: difference falls within error
+#         no cache B:    42505.4 i/s - 4.20x  slower

data/docs/README.md

@@ -36,11 +36,11 @@ Why did we decide to build our own authorization gem instead of using the existi
 
 [Pundit][] has been our framework of choice for a long time. Being too _dead-simple_, it required a lot of hacking to fulfill business logic requirements.
 
-These _hacks_ later become into Action Policy (initially, we even called it "Pundit, re-visited").
+These _hacks_ later became Action Policy (initially, we even called it "Pundit, re-visited").
 
 We also took a few ideas from [CanCanCan][]—such as [default rules and rule aliases](./aliases.md).
 
-It is also worth noting that Action Policy (despite from a _Railsy_ name) is designed to be **Rails-free**. On the other hand, it contains some Rails-specific extensions and seamlessly integrates into the framework.
+It is also worth noting that Action Policy (despite having a _Railsy_ name) is designed to be **Rails-free**. On the other hand, it contains some Rails-specific extensions and seamlessly integrates into the framework.
 
 So, what are the main reasons to consider Action Policy as your authorization tool?
 
@@ -50,7 +50,7 @@ So, what are the main reasons to consider Action Policy as your authorization to
 
 - **Code Organization**: use [namespaces](./namespaces.md) to organize your policies (for example, when you have multiple authorization strategies); add [pre-checks](./pre_checks.md) to make rules more readable and better express your business-logic.
 
-- ...and more: [testability](./testing.md), [i18n](./i18n.md) integrations, [actionable errors](./reasons.md).
+- **...and more**: [testability](./testing.md), [i18n](./i18n.md) integrations, [actionable errors](./reasons.md).
 
 Learn more about the motivation behind the Action Policy and its features by watching this [RailsConf talk](https://www.youtube.com/watch?v=NVwx0DARDis).
 

data/docs/_sidebar.md

@@ -5,17 +5,21 @@
   * [Non-Rails Usage](non_rails.md)
   * [Testing](testing.md)
 * Features
+  * [Authorization Behaviour](behaviour.md)
   * [Policy Lookup](lookup_chain.md)
   * [Authorization Context](authorization_context.md)
   * [Aliases](aliases.md)
   * [Pre-Checks](pre_checks.md)
+  * [Scoping](scoping.md)
   * [Caching](caching.md)
   * [Namespaces](namespaces.md)
   * [Failure Reasons](reasons.md)
   * [Instrumentation](instrumentation.md)
   * [I18n Support](i18n.md)
+  * [Debugging](debugging.md)
 * Tips & Tricks
   * [From Pundit to Action Policy](./pundit_migration.md)
+  * [Dealing with Decorators](./decorators.md)
   * [Controller Action Aliases](controller_action_aliases.md)
 * Customize
   * [Base Policy](custom_policy.md)

data/docs/aliases.md

@@ -76,11 +76,14 @@ class SuperPolicy < ApplicationPolicy
 
   alias_rule :update?, :destroy?, :create?, to: :edit?
 
-  def manage?; end
+  def manage?
+  end
 
-  def edit?; end
+  def edit?
+  end
 
-  def index?; end
+  def index?
+  end
 end
 
 class SubPolicy < AbstractPolicy
@@ -88,7 +91,8 @@ class SubPolicy < AbstractPolicy
 
   alias_rule :index?, :update?, to: :manage?
 
-  def create?; end
+  def create?
+  end
 end
 ```
 
@@ -102,7 +106,7 @@ Authorizing against the SuperPolicy:
 * `index?` will resolve to `index?`
 * `something?` will resolve to `manage?`
 
-Authorizing against the SuBPolicy:
+Authorizing against the SubPolicy:
 
 * `index?` will resolve to `manage?`
 * `update?` will resolve to `manage?`

data/docs/authorization_context.md

@@ -8,7 +8,7 @@ You must configure authorization context in **two places**: in the policy itself
 
 By default, `ActionPolicy::Base` includes `user` as authorization context. If you don't need it, you have to [build your own base policy](custom_policy.md).
 
-To specify additional contexts, you should use `authorize` method:
+To specify additional contexts, you should use the `authorize` method:
 
 ```ruby
 class ApplicationPolicy < ActionPolicy::Base
@@ -31,3 +31,61 @@ class ApplicationController < ActionController::Base
   authorize :account, through: :current_account
 end
 ```
+
+## Nested Policies vs Contexts
+
+See also: [action_policy#36](https://github.com/palkan/action_policy/issues/36) and [action_policy#37](https://github.com/palkan/action_policy/pull/37)
+
+When you call another policy from the policy object (e.g. via `allowed_to?` method),
+the context of the current policy is passed to the _nested_ policy.
+
+That means that if the nested policy has a different authorization context, we won't be able
+to build it (event if you configure all the required keys in the controller).
+
+For example:
+
+```ruby
+class UserPolicy < ActionPolicy::Base
+  authorize :user
+
+  def show?
+    allowed_to?(:show?, record.profile)
+  end
+end
+
+class ProfilePolicy < ActionPolicy::Base
+  authorize :user, :account
+end
+
+class ApplicationController < ActionController::Base
+  authorize :user, through: :current_user
+  authorize :account, through: :current_account
+end
+
+class UsersController < ApplicationController
+  def show
+    user = User.find(params[:id])
+
+    authorize! user #=> raises "Missing policy authorization context: account"
+  end
+end
+```
+
+That means that **all the policies that could be used together MUST share the same set of authorization contexts** (or at least the _parent_ policies contexts must be subsets of the nested policies contexts).
+
+
+## Explicit context
+
+You can override the _implicit_ authorization context (generated with `authorize` method) in-place
+by passing the `context` option:
+
+```ruby
+def show
+  user = User.find(params[:id])
+
+  authorize! user, context: {account: user.account}
+end
+```
+
+**NOTE:** the explictly provided context is merged with the implicit one (i.e. you can specify
+only the keys you want to override).

data/docs/behaviour.md

@@ -0,0 +1,113 @@
+# Action Policy Behaviour
+
+Action Policy provides a mixin called `ActionPolicy::Behaviour` which adds authorization methods to your classes.
+
+## Usage
+
+Let's make our custom _service_ object aware of authorization:
+
+```ruby
+class PostUpdateAction
+  # First, we should include the behaviour
+  include ActionPolicy::Behaviour
+
+  # Secondly, provide authorization subject (performer)
+  authorize :user
+
+  attr_reader :user
+
+  def initialize(user)
+    @user = user
+  end
+
+  def call(post, params)
+    # Now we can use authorization methods
+    authorize! post, to: :update?
+
+    post.update!(params)
+  end
+end
+```
+
+`ActionPolicy::Behaviour` provides `authorize` class-level method to configure [authorization context](authorization_context.md) and the instance-level methods: `authorize!`, `allowed_to?` and `authorized`:
+
+### `authorize!`
+
+This is a _guard-method_ which raises an `ActionPolicy::Unauthorized` exception
+if authorization failed (i.e. policy rule returns false):
+
+```ruby
+# `to` is a name of the policy rule to apply
+authorize! post, to: :update?
+```
+
+### `allowed_to?`
+
+This is a _predicate_ version of `authorize!`: it returns true if authorization succeed and false otherwise:
+
+```ruby
+# the first argument is the rule to apply
+# the second one is the target
+if allowed_to?(:edit?, post)
+  # ...
+end
+```
+
+### `authorized`
+
+See [scoping](./scoping.md) docs.
+
+## Policy lookup
+
+All three instance methods (`authorize!`, `allowed_to?`, `authorized`) uses the same
+`policy_for` to lookup a policy class for authorization target. So, you can provide additional options to control the policy lookup process:
+
+- Explicitly specify policy class using `with` option:
+
+```ruby
+allowed_to?(:edit?, post, with: SpecialPostPolicy)
+```
+
+- Provide a [namespace](./namespaces.md):
+
+```ruby
+# Would try to lookup Admin::PostPolicy first
+authorize! post, to: :destroy?, namespace: Admin
+```
+
+## Implicit authorization target
+
+You can omit the authorization target for all the methods by defining an _implicit authorization target_:
+
+```ruby
+class PostActions
+  include ActionPolicy::Behaviour
+
+  authorize :user
+
+  attr_reader :user, :post
+
+  def initialize(user, post)
+    @user = user
+    @post = post
+  end
+
+  def update(params)
+    # post is used here implicitly as a target
+    authorize! to: :update
+
+    post.update!(params)
+  end
+
+  def destroy
+    # post is used here implicitly as a target
+    authorize! to: :destroy
+
+    post.destroy!
+  end
+
+  def implicit_authorization_target
+    post
+  end
+end
+```

data/docs/caching.md

@@ -139,10 +139,10 @@ class StagePolicy < ApplicationPolicy
   def full_access?
     !record.funnel.is_private? ||
       user.permissions
-          .where(
-            funnel_id: record.funnel_id,
-            full_access: true
-          ).exists?
+        .where(
+          funnel_id: record.funnel_id,
+          full_access: true
+        ).exists?
   end
 end
 ```
@@ -177,6 +177,8 @@ Where `cache_namespace` is equal to `"acp:#{MAJOR_GEM_VERSION}.#{MINOR_GEM_VERSI
 
 If any object does not respond to `#policy_cache_key`, we fallback to `#cache_key`. If `#cache_key` is not defined, an `ArgumentError` is raised.
 
+**NOTE:** if your `#cache_key` method is performance-heavy (e.g. like the `ActiveRecord::Relation`'s one), we recommend to explicitly define the `#policy_cache_key` method on the corresponding class to avoid unnecessary load. See also [action_policy#55](https://github.com/palkan/action_policy/issues/55).
+
 You can define your own `cache_key` / `cache_namespace` / `context_cache_key` methods for policy class to override this logic.
 
 #### Invalidation

data/docs/custom_policy.md

@@ -4,7 +4,6 @@
 
 It looks like this:
 
-<span style="display:none;"># rubocop:disable Style/ClassAndModuleChildren</span>
 
 ```ruby
 class ActionPolicy::Base
@@ -38,7 +37,7 @@ class ActionPolicy::Base
 end
 ```
 
-<span style="display:none;"># rubocop:enable Style/ClassAndModuleChildren</span>
+
 
 You can write your `ApplicationPolicy` from scratch instead of inheriting from `ActionPolicy::Base`
 if the defaults above do not fit your needs. The only required component is `ActionPolicy::Policy::Core`:

data/docs/debugging.md

@@ -0,0 +1,55 @@
+# Debug Helpers
+
+**NOTE:** this functionality requires two additional gems to be available in the app:
+- [unparser](https://github.com/mbj/unparser)
+- [method_source](https://github.com/banister/method_source).
+
+We usually describe policy rules using _boolean expressions_ (e.g. `A or (B and C)` where each of `A`, `B` and `C` is a simple boolean expression or predicate method).
+
+When dealing with complex policies, it could be hard to figure out which predicate/check made policy to fail.
+
+The `Policy#pp(rule)` method aims to help debug such situations.
+
+Consider a (synthetic) example:
+
+```ruby
+def feed?
+  (admin? || allowed_to?(:access_feed?)) &&
+    (user.name == "Jack" || user.name == "Kate")
+end
+
+```
+
+Suppose that you want to debug this rule ("Why does it return false?").
+You can drop a [`binding.pry`](https://github.com/deivid-rodriguez/pry-byebug) (or `binding.irb`) right at the beginning of the method:
+
+```ruby
+def feed?
+  binding.pry # rubocop:disable Lint/Debugger
+  #...
+end
+```
+
+Now, run your code and trigger the breakpoint (i.e., run the method):
+
+```
+# now you can preview the execution of the rule using the `pp` method (defined on the policy instance)
+pry> pp :feed?
+MyPolicy#feed?
+↳ (
+    admin? #=> false
+    OR
+    allowed_to?(:access_feed?) #=> true
+  )
+  AND
+  (
+    user.name == "Jack" #=> false
+    OR
+    user.name == "Kate" #=> true
+  )
+
+# you can also check other rules or methods as well
+pry> pp :admin?
+MyPolicy#admin?
+↳ user.admin? #=> false
+```

data/docs/decorators.md

@@ -0,0 +1,27 @@
+# Dealing with Decorators
+
+Ref: [action_policy#7](https://github.com/palkan/action_policy/issues/7).
+
+Since Action Policy [lookup mechanism](./lookup_chain.md) relies on the target
+record's class properties (names, methods) it could break when using with _decorators_.
+
+To make `authorize!` and other [behaviour](./behaviour.md) methods work seamlessly with decorated
+objects, you might want to _enhance_ the `policy_for` method.
+
+For example, when using the [Draper](https://github.com/drapergem/draper) gem:
+
+```ruby
+module ActionPolicy
+  module Draper
+    def policy_for(record:, **opts)
+      # From https://github.com/GoodMeasuresLLC/draper-cancancan/blob/master/lib/draper/cancancan.rb
+      record = record.model while record.is_a?(Draper::Decorator)
+      super(record: record, **opts)
+    end
+  end
+end
+
+class ApplicationController < ActionController::Base
+  prepend ActionPolicy::Draper
+end
+```