action_policy 0.4.3 → 0.5.3

data/docs/instrumentation.md

@@ -1,84 +0,0 @@
-# Instrumentation
-
-Action Policy integrates with [Rails instrumentation system](https://guides.rubyonrails.org/active_support_instrumentation.html), `ActiveSupport::Notifications`.
-
-## 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?`).
-
-### `action_policy.init`
-
-This event is triggered every time a new policy object is initialized.
-
-The event contains the following information:
-
-- `:policy` – policy class name.
-
-This event is useful if you want to track the number of initialized policies per _action_ (for example, when you want to ensure that
-the [memoization](caching.md) works as expected).
-
-## 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

@@ -1,17 +0,0 @@
-# Policy Lookup
-
-Action Policy tries to automatically infer policy class from the target using the following _probes_:
-
-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.
-
-You can call `ActionPolicy.lookup(record, options)` to infer policy class for the record.
-
-When no policy class is found, an `ActionPolicy::NotFound` error is raised.
-
-You can [customize lookup](custom_lookup_chain.md) logic if necessary.

data/docs/namespaces.md

@@ -1,77 +0,0 @@
-# Namespaces
-
-Action Policy can lookup policies with respect to the current execution _namespace_ (i.e., authorization class module).
-
-Consider an example:
-
-```ruby
-module Admin
-  class UsersController < ApplictionController
-    def index
-      # uses Admin::UserPolicy if any, otherwise fallbacks to UserPolicy
-      authorize!
-    end
-  end
-end
-```
-
-Module nesting is also supported:
-
-```ruby
-module Admin
-  module Client
-    class UsersController < ApplictionController
-      def index
-        # lookup for Admin::Client::UserPolicy -> Admin::UserPolicy -> UserPolicy
-        authorize!
-      end
-    end
-  end
-end
-```
-
-**NOTE**: 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 namespaces into account):
-
-```ruby
-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:
-
-```ruby
-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`:
-
-```ruby
-def authorization_namespace
-  return ::Admin if current_user.admin?
-  return ::Staff if current_user.staff?
-  # fallback to current namespace
-  super
-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 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)).
-
-It could be disabled by setting `ActionPolicy::LookupChain.namespace_cache_enabled = false`. It's enabled by default unless `RACK_ENV` env var is specified and is not equal to `"production"` (e.g. when `RACK_ENV=test` the cache is disabled).
-
-When using Rails it's enabled only in production mode but could be configured through setting the `config.action_policy.namespace_cache_enabled` parameter.

data/docs/non_rails.md

@@ -1,28 +0,0 @@
-# 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?` / `authorized` methods, you will have to include [`ActionPolicy::Behaviour`](./behaviour.md) into your class (where you want to perform authorization):
-
-```ruby
-class PostUpdateAction
-  include ActionPolicy::Behaviour
-
-  # provide authorization subject (performer)
-  authorize :user
-
-  attr_reader :user
-
-  def initialize(user)
-    @user = user
-  end
-
-  def call(post, params)
-    authorize! post, to: :update?
-
-    post.update!(params)
-  end
-end
-```

data/docs/pre_checks.md

@@ -1,57 +0,0 @@
-# Pre-Checks
-
-Consider a typical situation when you start most—or even all—of your rules with the same predicates.
-
-For example, when you have a super-user role in the application:
-
-```ruby
-class PostPolicy < ApplicationPolicy
-  def show?
-    user.super_admin? || record.published
-  end
-
-  def update?
-    user.super_admin? || (user.id == record.user_id)
-  end
-
-  # more rules
-end
-```
-
-Action Policy allows you to extract the common parts from rules into _pre-checks_:
-
-```ruby
-class PostPolicy < ApplicationPolicy
-  pre_check :allow_admins
-
-  def show?
-    record.published
-  end
-
-  def update?
-    user.id == record.user_id
-  end
-
-  private
-
-  def allow_admins
-    allow! if user.super_admin?
-  end
-end
-```
-
-Pre-checks act like _callbacks_: you can add multiple pre-checks, specify `except` and `only` options, and skip already defined pre-checks if necessary:
-
-```ruby
-class UserPolicy < ApplicationPolicy
-  skip_pre_check :allow_admins, only: :destroy?
-
-  def destroy?
-    user.admin? && !record.admin?
-  end
-end
-```
-
-To halt the authorization process within a pre-check, you must return either `allow!` or `deny!` call value. When any other value is returned, the pre-check is ignored, and the rule is called (or next pre-check).
-
-**NOTE**: pre-checks are available only if you inherit from `ActionPolicy::Base` or include `ActionPolicy::Policy::PreCheck` into your `ApplicationPolicy`.

data/docs/pundit_migration.md

@@ -1,80 +0,0 @@
-# Migrate from Pundit to Action Policy
-
-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.
-
-### 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](reasons), [I18n integration](i18n), [cache](caching) and other Action Policy features!

data/docs/quick_start.md

@@ -1,118 +0,0 @@
-# Quick Start
-
-## Installation
-
-Install Action Policy with RubyGems:
-
-```ruby
-gem install action_policy
-```
-
-Or add `action_policy` to your application's `Gemfile`:
-
-```ruby
-gem "action_policy"
-```
-
-And then execute:
-
-    $ bundle
-
-## Basic usage
-
-The core component of Action Policy is a _policy class_. Policy class describes how you control access to resources.
-
-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 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:
-
-```ruby
-class ApplicationPolicy < ActionPolicy::Base
-end
-```
-
-You could use the following command to generate it when using Rails:
-
-```sh
-rails generate action_policy:install
-```
-
-**NOTE:** it is not necessary to inherit from `ActionPolicy::Base`; instead, you can [construct basic policy](custom_policy.md) choosing only the components you need.
-
-Rules must be public methods on the class. Using private methods as rules will raise an error.
-
-Consider a simple example:
-
-```ruby
-class PostPolicy < ApplicationPolicy
-  # everyone can see any post
-  def show?
-    true
-  end
-
-  def update?
-    # `user` is a performing subject,
-    # `record` is a target object (post we want to update)
-    user.admin? || (user.id == record.user_id)
-  end
-end
-```
-
-Now you can easily add authorization to your Rails\* controller:
-
-```ruby
-class PostsController < ApplicationController
-  def update
-    @post = Post.find(params[:id])
-    authorize! @post
-
-    if @post.update(post_params)
-      redirect_to @post
-    else
-      render :edit
-    end
-  end
-end
-```
-
-\* See [Non-Rails Usage](non_rails.md) on how to add `authorize!` to any Ruby project.
-
-In the above case, Action Policy automatically infers a policy class and a rule to verify access: `@post -> Post -> PostPolicy`, rule is inferred from the action name (`update -> update?`), and `current_user` is used as `user` within the policy by default (read more about [authorization context](authorization_context.md)).
-
-When authorization is successful (i.e., the corresponding rule returns `true`), nothing happens, but in case of an authorization failure `ActionPolicy::Unauthorized` error is raised:
-
-```ruby
-rescue_from ActionPolicy::Unauthorized do |ex|
-  # Exception object contains the following information
-  ex.policy #=> policy class, e.g. UserPolicy
-  ex.rule #=> applied rule, e.g. :show?
-end
-```
-
-There is also an `allowed_to?` method which returns `true` or `false` and could be used, for example, in views:
-
-```erb
-<% @posts.each do |post| %>
-  <li><%= post.title %>
-    <% if allowed_to?(:edit?, post) %>
-      = link_to "Edit", post
-    <% end %>
-  </li>
-<% end %>
-```
-
-Although Action Policy tries to [infer the corresponding policy class](policy_lookup.md) and rule itself, there could be a situation when you want to specify those values explicitly:
-
-```ruby
-# specify the rule to verify access
-authorize! @post, to: :update?
-
-# specify policy class
-authorize! @post, with: CustomPostPolicy
-
-# or
-allowed_to? :edit?, @post, with: CustomPostPolicy
-```