action_policy 0.2.4 → 0.3.0.beta1

data/docs/i18n.md

@@ -1,5 +1,44 @@
 # I18n Support
 
-🛠 **WORK IN PROGRESS**
+`ActionPolicy` integrates with [`i18n`][] to support localizable `full_messages` for [reasons](./reasons.md) and the execution result's `message`:
 
-Follow [the issue](https://github.com/palkan/action_policy/issues/15).
+```ruby
+class ApplicationController < ActionController::Base
+  rescue_from ActionPolicy::Unauthorized do |ex|
+    p ex.result.message #=> "You do not have access to the stage"
+    p ex.result.reasons.full_messages #=> ["You do not have access to the stage"]
+  end
+end
+```
+
+The message contains a string for the _rule_ that was called, while `full_messages` contains the list of reasons, why `ActionPolicy::Unauthorized` has been raised. You can find more information about tracking failure reasons [here](./reasons.md).
+
+## Configuration
+
+`ActionPolicy` doesn't provide any localization out-of-the-box and uses "You are not authorized to perform this action" as the default message.
+
+You can add your app-level default fallback by providing the `action_policy.unauthorized` key value.
+
+When using **Rails**, all you need is to add translations to any file under the `config/locales` folder (or create a new file, e.g. `config/locales/policies.yml`).
+
+Non-Rails projets should configure [`i18n`][] gem manually:
+
+```ruby
+I18n.load_path << Dir[File.expand_path("config/locales") + "/*.yml"]
+```
+
+## Translations lookup
+
+`ActionPolicy` uses the `action_policy` scope. Specific policies translations must be stored inside the `policy` sub-scope.
+
+The following algorithm is used to find out the translation for a policy with a class `klass` and rule `rule`:
+1. Translation for `"#{klass.identifier}.#{rule}"` key, when `self.identifier =` is not specified then underscored class name without the _Policy_ suffix would be used (e.g. `GuestUserPolicy` turns into `guest_user:` scope)
+2. Repeat step 1 for each ancestor which looks like a policy (`.respond_to?(:identifier)?`) up to `ActionPolicy::Base`
+3. Use `#{rule}` key
+4. Use `en.action_policy.unauthorized` key
+5. Use a default message provided by the gem
+
+For example, given a `GuestUserPolicy` class which is inherited from `DefaultUserPolicy` and a rule `feed?`, the following list of possible translation keys would be used: `[:"action_policy.policy.guest_user.feed?", :"action_policy.policy.default_user.feed?", :"action_policy.policy.feed?", :"action_policy.unauthorized"]`
+
+
+[`i18n`]: https://github.com/svenfuchs/i18n

data/docs/instrumentation.md

@@ -1,5 +1,73 @@
 # Instrumentation
 
-🛠 **WORK IN PROGRESS**
+Action Policy integrates with [Rails instrumentation system](https://guides.rubyonrails.org/active_support_instrumentation.html), `ActiveSupport::Notifications`.
 
-See [the PR](https://github.com/palkan/action_policy/pull/4).
+## Events
+
+### `action_policy.apply_rule`
+
+This event is triggered every time a policy rule is applied:
+- when `authorize!` is called
+- when `allowed_to?` is called within the policy or the [behaviour](behaviour)
+- when `apply_rule` is called explicitly (i.e. `SomePolicy.new(record, context).apply_rule(record)`).
+
+The event contains the following information:
+- `:policy` – policy class name
+- `:rule` – applied rule (String)
+- `:value` – the result of the rule application (true of false)
+- `:cached` – whether we hit the [cache](caching)\*.
+
+\* This parameter tracks only the cache store usage, not memoization.
+
+You can use this event to track your policy cache usage and also detect _slow_ checks.
+
+Here is an example code for sending policy stats to [Librato](https://librato.com/)
+using [`librato-rack`](https://github.com/librato/librato-rack):
+
+```ruby
+ActiveSupport::Notifications.subscribe("action_policy.apply_rule") do |event, started, finished, _, data|
+  # Track hit and miss events separately (to display two measurements)
+  measurement = "#{event}.#{(data[:cached] ? "hit" : "miss")}"
+  # show ms times
+  timing = ((finished - started) * 1000).to_i
+  Librato.tracker.check_worker
+  Librato.timing measurement, timing, percentile: [95, 99]
+end
+```
+
+### `action_policy.authorize`
+
+This event is identical to `action_policy.apply_rule` with the one difference:
+**it's only triggered when `authorize!` method is called**.
+
+The motivation behind having a separate event for this method is to monitor the number of failed
+authorizations: the high number of failed authorizations usually means that we do not take
+into account authorization rules in the application UI (e.g., we show a "Delete" button to the user not
+permitted to do that).
+
+The `action_policy.apply_rule` might have a large number of failures, 'cause it also tracks the usage of non-raising applications (i.e. `allowed_to?`).
+
+## Turn off instrumentation
+
+Instrumentation is enabled by default. To turn it off add to your configuration:
+
+```ruby
+config.action_policy.instrumentation_enabled = false
+```
+
+**NOTE:** changing this setting after the application has been initialized doesn't take any effect.
+
+## Non-Rails usage
+
+If you don't use Rails itself but have `ActiveSupport::Notifications` available in your application,
+you can use the instrumentation feature with some additional configuration:
+
+```ruby
+# Enable `apply_rule` event by extending the base policy class
+require "action_policy/rails/policy/instrumentation"
+ActionPolicy::Base.include ActionPolicy::Policy::Rails::Instrumentation
+
+# Enabled `authorize` event by extending the authorizer class
+require "action_policy/rails/authorizer"
+ActionPolicy::Authorizer.singleton_class.prepend ActionPolicy::Rails::Authorizer
+```

data/docs/lookup_chain.md

@@ -2,10 +2,11 @@
 
 Action Policy tries to automatically infer policy class from the target using the following _probes_:
 
-1. If the target responds to `policy_class`, then use it;
-2. If the target's class responds to `policy_class`, then use it;
-3. If the target's class responds to `policy_name`, then use it (the `policy_name` should end with `Policy` as it's not appended automatically);
-4. Otherwise, use `#{target.class.name}Policy`.
+1. If the target is a `Symbol`, then use `"#{target.to_s.classify}Policy"` as a `policy_name` (see below);
+2. If the target responds to `policy_class`, then use it;
+3. If the target's class responds to `policy_class`, then use it;
+4. If the target or the target's class responds to `policy_name`, then use it (the `policy_name` should end with `Policy` as it's not appended automatically);
+5. Otherwise, use `#{target.class.name}Policy`.
 
 > \* [Namespaces](namespaces.md) could be also be considered when `namespace` option is set.
 

data/docs/namespaces.md

@@ -68,7 +68,7 @@ end
 
 **NOTE**: namespace support is an extension for `ActionPolicy::Behaviour` and could be included with `ActionPolicy::Behaviours::Namespaced` (included into Rails controllers and channel integrations by default).
 
-## Namespace resultion cache
+## Namespace resolution cache
 
 We cache namespaced policy resolution for better performance (it could affect performance when we look up a policy from a deeply nested module context, see the [benchmark](https://github.com/palkan/action_policy/blob/master/benchmarks/namespaced_lookup_cache.rb)).
 

data/docs/non_rails.md

@@ -1,9 +1,10 @@
 # Using with Ruby applications
 
 Action Policy is designed to be independent of any framework and does not have specific dependencies on Ruby on Rails.
+
 You can [write your policies](writing_policies.md) for non-Rails applications the same way as you would do for Rails applications.
 
-In order to have `authorize!` / `allowed_to?` methods, you will have to include `ActionPolicy::Behaviour` into your class (where you want to perform authorization):
+In order to have `authorize!` / `allowed_to?` / `authorized` methods, you will have to include [`ActionPolicy::Behaviour`](./behaviour.md) into your class (where you want to perform authorization):
 
 ```ruby
 class PostUpdateAction
@@ -25,5 +26,3 @@ class PostUpdateAction
   end
 end
 ```
-
-`ActionPolicy::Behaviour` provides `authorize` class-level method to configure [authorization context](authorization_context.rb) and two instance-level methods: `authorize!` and `allowed_to?`.

data/docs/pundit_migration.md

@@ -1,5 +1,80 @@
 # Migrate from Pundit to Action Policy
 
-🛠 **WORK IN PROGRESS**
+Migration from Pundit to Action Policy could be done in a progressive way: first, we make Pundit polices and authorization helpers use Action Policy under the hood, then you can rewrite policies in the Action Policy way.
 
-Draft is available [here](https://gist.github.com/palkan/a4c482eeb8453ef6b103ee05f8c2f077).
+### Phase 1. Quacking like a Pundit.
+
+#### Step 1. Prepare controllers.
+
+- Remove `include Pundit` from ApplicationController
+
+- Add `authorize` method:
+
+```ruby
+def authorize(record, rule = nil)
+  options = {}
+  options[:to] = rule unless rule.nil?
+
+  authorize! record, **options
+end
+```
+
+- Configure [authorization context](authorization_context) if necessary, e.g. add `authorize :current_user, as: :user` to `ApplicationController` (**NOTE:** added automatically in Rails apps)
+
+- Add `policy` and `policy_scope` helpers:
+
+```ruby
+helper_method :policy
+helper_method :policy_scope
+
+def policy(record)
+  policy_for(record)
+end
+
+def policy_scope(scope)
+  authorized scope
+end
+
+```
+
+**NOTE**: `policy` defined above is not equal to `allowed_to?` since it doesn't take into account pre-checks.
+
+#### Step 2. Prepare policies.
+
+We assume that you have a base class for all your policies, e.g. `ApplicationPolicy`.
+
+Then do the following:
+- Add `include ActionPolicy::Policy::Core` to `ApplicationPolicy`
+
+- Update `ApplicationPolicy#initialize`:
+
+```ruby
+def initialize(target, user:)
+  # ...
+end
+```
+
+- [Rewrite scopes](scoping).
+
+Unfortunately, there is no easy way to migrate Pundit class-based scope to Action Policies scopes.
+
+#### Step 3. Replace RSpec helper:
+
+We provide a Pundit-compatibile syntax for RSpec tests:
+
+```
+# Remove DSL
+# require "pundit/rspec"
+#
+# Add Action Policy Pundit DSL
+require "action_policy/rspec/pundit_syntax"
+```
+
+### Phase 2. No more Pundit.
+
+When everything is green, it's time to fully migrate to ActionPolicy:
+- make ApplicationPolicy inherit from `ActionPolicy::Base`
+- migrate view helpers (from `policy(..)` to `allowed_to?`, from `policy_scope` to `authorized`)
+- re-write specs using simple non-DSL syntax (or [Action Policy RSpec syntax](testing#rspec-dsl))
+- add [authorization tests](testing#testing-authorization) (add `require 'action_policy/rspec'`)
+- use [Reasons](), [I18n integration](i18n), [cache](caching) and other Action Policy features!

data/docs/quick_start.md

@@ -2,13 +2,13 @@
 
 ## Installation
 
-To install Action Policy with RubyGems:
+Install Action Policy with RubyGems:
 
 ```ruby
 gem install action_policy
 ```
 
-Or add this line to your application's `Gemfile`:
+Or add `action_policy` to your application's `Gemfile`:
 
 ```ruby
 gem "action_policy"
@@ -22,10 +22,10 @@ And then execute:
 
 The core component of Action Policy is a _policy class_. Policy class describes how you control access to resources.
 
-We suggest that you have a separate policy class for each resource and encourage you to follow the conventions:
+We suggest having a separate policy class for each resource and encourage you to follow these conventions:
 - put policies into the `app/policies` folder (when using with Rails);
-- name policies using the corresponding resource name (model name) with a `Policy` suffix, e.g. `Post -> PostPolicy`;
-- name rules using a predicate form of the corresponding activity (typically, a controller's action), e.g. `PostsController#update -> PostsPolicy#update?`.
+- name policies using the corresponding singular resource name (model name) with a `Policy` suffix, e.g. `Post -> PostPolicy`;
+- name rules using a predicate form of the corresponding activity (typically, a controller's action), e.g. `PostsController#update -> PostPolicy#update?`.
 
 We also recommend to use an application-specific `ApplicationPolicy` with a global configuration to inherit from:
 

data/docs/rails.md

@@ -1,9 +1,11 @@
 # Using with Rails
 
-Action Policy seamlessly integrates Ruby on Rails applications seamlessly.
+Action Policy seamlessly integrates with Ruby on Rails applications.
 
 In most cases, you do not have to do anything except writing policy files and adding `authorize!` calls.
 
+**NOTE:** both controllers and channels extensions are built on top of the Action Policy [behaviour](./behaviour.md) mixin.
+
 ## Controllers integration
 
 Action Policy assumes that you have a `current_user` method which specifies the current authenticated subject (`user`).
@@ -56,7 +58,8 @@ In that case, Action Policy tries to infer the resource class from the controlle
 class PostsController < ApplicationPolicy
   def index
     # Uses Post class as a resource implicitly.
-    # NOTE: it just calls `controller_name.classify.safe_constantize`
+    # NOTE: it just calls `controller_name.classify.safe_constantize`,
+    # you can override this by defining `implicit_authorization_target` method.
     authorize!
   end
 end

data/docs/reasons.md

@@ -32,8 +32,6 @@ end
 
 The reason key is the corresponding policy [identifier](writing_policies.md#identifiers).
 
-**NOTE:** `full_messages` support hasn't been released yet. See [the issue](https://github.com/palkan/action_policy/issues/15).
-
 You can also wrap _local_ rules into `allowed_to?` to populate reasons:
 
 ```ruby
@@ -55,9 +53,58 @@ p ex.result.reasons.details #=> { applicant: [:view_applicants?] }
 p ex.result.reasons.details #=> { stage: [:show?] }
 ```
 
+## Detailed Reasons
+
+**NOTE:** this feature hasn't been released yet and planned for 0.3.0 release.
+You can use it now by installing the gem from GitHub master:
+
+```ruby
+gem "action_policy", github: "palkan/action_policy"
+```
+
+You can provide additional details to your failure reasons by using a `details: { ... }` option:
+
+```ruby
+class ApplicantPolicy < ApplicationPolicy
+  def show?
+    allowed_to?(:show?, object.stage)
+  end
+end
+
+class StagePolicy < ApplicationPolicy
+  def show?
+    # Add stage title to the failure reason (if any)
+    # (could be used by client to show more descriptive message)
+    details[:title] = record.title
+
+    # then perform the checks
+    user.stages.where(id: record.id).exists?
+  end
+end
+
+# when accessing the reasons
+p ex.result.reasons.details #=> { stage: [{show?: {title: "Onboarding"}] }
+```
+
+**NOTE**: when using detailed reasons, the `details` array contains as the last element
+a hash with ALL details reasons for the policy (in a form of `<rule> => <details>`).
 
+The additional details are especially helpful when combined with localization, 'cause you can you them as interpolation data source for your translations. For example, for the above policy:
+
+```yml
+en:
+  policy:
+    stage:
+      show?: "The %{title} stage is not accessible"
+```
+
+And then when you call `full_messages`:
+
+```ruby
+p ex.result.reasons.full_messages #=> The Onboarding stage is not accessible
+```
 
-**What is the point of failure reasons?**
+**P.S. What is the point of failure reasons?**
 
 Failure reasons helps you to write _actionable_ error messages, i.e. to provide a user with helpful feedback.
 

data/docs/scoping.md

@@ -0,0 +1,262 @@
+# Scoping
+
+**NOTE:** this feature hasn't been released yet and planned for 0.3.0 release.
+You can use it now by installing the gem from GitHub master:
+
+```ruby
+gem "action_policy", github: "palkan/action_policy"
+```
+
+By _scoping_ we mean an ability to use policies to _scope data_ (or _filter/modify/transform/choose-your-verb_).
+
+The most common situation is when you want to _scope_ ActiveRecord relations depending
+on the current user permissions. Without policies it could look like this:
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    @posts =
+      if current_user.admin?
+        Post.all
+      else
+        Post.where(user: current_user)
+      end
+  end
+end
+```
+
+That's a very simplified example. In practice scoping rules might be more complex, and it's likely that we would use them in multiple places.
+
+Action Policy allows you to define scoping rules within a policy class and use them with the help of `authorized_scope` method (`authorized` alias is also available):
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    @posts = authorized_scope(Post.all)
+  end
+end
+
+class PostPolicy < ApplicationPolicy
+  relation_scope do |relation|
+    next relation if user.admin?
+    relation.where(user: user)
+  end
+end
+```
+
+## Define scopes
+
+To define scope you should use either `scope_for` or `smth_scope` methods in your policy:
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  # define a scope of a `relation` type
+  scope_for :relation do |relation|
+    relation.where(user: user)
+  end
+
+  # define a scope of `my_data` type,
+  # which acts on hashes
+  scope_for :my_data do |data|
+    next data if user.admin?
+    data.delete_if { |k, _| SENSITIVE_KEYS.include?(k) }
+  end
+end
+```
+
+Scopes have _types_: different types of scopes are meant to be applied to different data types.
+
+You can specify multiple scopes (_named scopes_) for the same type providing a scope name:
+
+```ruby
+class EventPolicy < ApplictionPolicy
+  scope_for :relation, :own do |relation|
+    relation.where(owner: user)
+  end
+end
+```
+
+When the second argument is not specified, the `:default` is implied as the scope name.
+
+Also, there are cases where it might be easier to add options to existing scope than create a new one.
+
+For example, if you use soft-deletion and your logic inside a scope depends on if deleted records are included, you can add `with_deleted` option:
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  scope_for :relation do |relation, with_deleted: false|
+    rel = some_logic(relation)
+    with_deleted ? rel.with_deleted : rel
+  end
+end
+```
+
+You can add as many options as you want:
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  scope_for :relation do |relation, with_deleted: false, magic_number: 42, some_required_option:|
+    # Your code
+  end
+end
+```
+## Apply scopes
+
+Action Policy behaviour (`ActionPolicy::Behaviour`) provides an `authorized` method which allows you to use scoping:
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    # The first argument is the target,
+    # which is passed to the scope block
+    #
+    # The second argument is the scope type
+    @posts = authorized_scope(Post, type: :relation)
+    #
+    # For named scopes provide `as` option
+    @events = authorized_scope(Event, type: :relation, as: :own)
+    #
+    # If you want to specify scope options provide `scope_options` option
+    @events = authorized_scope(Event, type: :relation, scope_options: {with_deleted: true})
+  end
+end
+```
+
+You can also specify additional options for policy class inference (see [behaviour docs](behaviour)). For example, to explicitly specify the policy class use:
+
+```ruby
+@posts = authorized_scope(Post, with: CustomPostPolicy)
+```
+
+## Using scopes within policy
+
+You can also use scopes within policy classes using the same `authorized_scope` method.
+For example:
+
+```ruby
+relation_scope(:edit) do |scope|
+  teachers = authorized_scope(Teacher.all, as: :edit)
+  scope
+    .joins(:teachers)
+    .where(teacher_id: teachers)
+end
+```
+
+## Using scopes explicitly
+
+To use scopes without including Action Policy [behaviour](behaviour)
+do the following:
+
+```ruby
+# initialize policy
+policy = ApplicantPolicy.new(user: user)
+# apply scope
+policy.apply_scope(User.all, type: :relation)
+```
+
+## Scope type inference
+
+Action Policy could look up a scope type if it's not specified and if _scope matchers_ were configured.
+
+Scope matcher is an object that implements `#===` (_case equality_) or a Proc. You can define it within a policy class:
+
+```ruby
+class ApplicationPolicy < ActionPolicy::Base
+  scope_matcher :relation, ActiveRecord::Relation
+
+  # use Proc to handle AR models classes
+  scope_matcher :relation, ->(target) { target < ActiveRecord::Base }
+
+  scope_matcher :custom, MyCustomClass
+end
+```
+
+Adding a scope matcher also adds a DSL to define scope rules (just a syntax sugar):
+
+```ruby
+class ApplicationPolicy < ActionPolicy::Base
+  scope_matcher :relation, ActiveRecord::Relation
+
+  # now you can define scope rules like this
+  relation_scope { |relation| relation }
+end
+```
+
+When `authorized_scope` is called without the explicit scope type, Action Policy uses matchers (in the order they're defined) to infer the type.
+
+## Rails integration
+
+Action Policy provides a couple of _scope matchers_ out-of-the-box for Active Record relations and Action Controller paramters.
+
+### Active Record scopes
+
+Scope type `:relation` is automatically applied to the object of `ActiveRecord::Relation` type.
+
+To define Active Record scopes you can use `relation_scope` macro (which is just an alias for `scope :relation`) in your policy:
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  # Equals `scope_for :active_record_relation do ...`
+  relation_scope do |scope|
+    if super_user? || admin?
+      scope
+    else
+      scope.joins(:accesses).where(accesses: {user_id: user.id})
+    end
+  end
+
+  # define named scope
+  relation_scope(:own) do |scope|
+    next scope.none if user.guest?
+    scope.where(user: user)
+  end
+end
+```
+
+**NOTE:** the `:active_record_relation` scoping is used if and only if an `ActiveRecord::Relation` is passed to `authorized`:
+
+```ruby
+def index
+  # BAD: Post is not a relation; raises an exception
+  @posts = authorized_scope(Post)
+
+  # GOOD:
+  @posts = authorized_scope(Post.all)
+end
+```
+
+### Action Controller parameters
+
+Use scopes of type `:params` if your strong parameters filterings depend on the current user:
+
+```ruby
+class UserPolicy < ApplicationPolicy
+  # Equals to `scope_for :action_controller_params do ...`
+  params_filter do |params|
+    if user.admin?
+      params.permit(:name, :email, :role)
+    else
+      params.permit(:name)
+    end
+  end
+
+  params_filter(:update) do |params|
+    params.permit(:name)
+  end
+end
+
+class UsersController < ApplicationController
+  def create
+    # Call `authorized_scope` on `params` object
+    @user = User.create!(authorized_scope(params.require(:user)))
+    # Or you can use `authorized` alias which fits this case better
+    @user = User.create!(authorized(params.require(:user)))
+    head :ok
+  end
+
+  def update
+    @user.update!(authorized_scope(params.require(:user), as: :update))
+    head :ok
+  end
+end
+```