RubyGems - action_policy - Versions diffs - 0.4.4 → 0.5.0 - Mend

action_policy 0.4.4 → 0.5.0

Files changed (97) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +203 -174
data/README.md +5 -4
data/lib/action_policy.rb +7 -1
data/lib/action_policy/behaviour.rb +22 -16
data/lib/action_policy/behaviours/policy_for.rb +10 -3
data/lib/action_policy/behaviours/scoping.rb +2 -1
data/lib/action_policy/behaviours/thread_memoized.rb +1 -3
data/lib/action_policy/ext/module_namespace.rb +1 -6
data/lib/action_policy/ext/policy_cache_key.rb +10 -30
data/lib/action_policy/i18n.rb +1 -1
data/lib/action_policy/lookup_chain.rb +29 -15
data/lib/action_policy/policy/aliases.rb +7 -12
data/lib/action_policy/policy/authorization.rb +8 -7
data/lib/action_policy/policy/cache.rb +11 -17
data/lib/action_policy/policy/core.rb +25 -12
data/lib/action_policy/policy/defaults.rb +3 -9
data/lib/action_policy/policy/execution_result.rb +3 -9
data/lib/action_policy/policy/pre_check.rb +19 -58
data/lib/action_policy/policy/reasons.rb +29 -19
data/lib/action_policy/policy/scoping.rb +5 -6
data/lib/action_policy/rails/controller.rb +6 -1
data/lib/action_policy/rails/policy/instrumentation.rb +1 -1
data/lib/action_policy/rspec/be_authorized_to.rb +5 -9
data/lib/action_policy/rspec/dsl.rb +1 -1
data/lib/action_policy/rspec/have_authorized_scope.rb +5 -7
data/lib/action_policy/utils/pretty_print.rb +21 -24
data/lib/action_policy/utils/suggest_message.rb +1 -3
data/lib/action_policy/version.rb +1 -1
data/lib/generators/action_policy/install/templates/{application_policy.rb → application_policy.rb.tt} +0 -0
data/lib/generators/action_policy/policy/policy_generator.rb +4 -1
data/lib/generators/action_policy/policy/templates/{policy.rb → policy.rb.tt} +0 -0
data/lib/generators/rspec/templates/{policy_spec.rb → policy_spec.rb.tt} +0 -0
data/lib/generators/test_unit/templates/{policy_test.rb → policy_test.rb.tt} +0 -0
metadata +29 -119
data/.gitattributes +0 -2
data/.github/ISSUE_TEMPLATE.md +0 -21
data/.github/PULL_REQUEST_TEMPLATE.md +0 -29
data/.github/bug_report_template.rb +0 -175
data/.gitignore +0 -15
data/.rubocop.yml +0 -54
data/.tidelift.yml +0 -6
data/.travis.yml +0 -31
data/Gemfile +0 -22
data/Rakefile +0 -27
data/action_policy.gemspec +0 -44
data/benchmarks/namespaced_lookup_cache.rb +0 -74
data/benchmarks/pre_checks.rb +0 -73
data/bin/console +0 -14
data/bin/setup +0 -8
data/docs/.nojekyll +0 -0
data/docs/CNAME +0 -1
data/docs/README.md +0 -79
data/docs/_sidebar.md +0 -27
data/docs/aliases.md +0 -122
data/docs/assets/docsify-search.js +0 -364
data/docs/assets/docsify.min.js +0 -3
data/docs/assets/fonts/FiraCode-Medium.woff +0 -0
data/docs/assets/fonts/FiraCode-Regular.woff +0 -0
data/docs/assets/images/banner.png +0 -0
data/docs/assets/images/cache.png +0 -0
data/docs/assets/images/cache.svg +0 -70
data/docs/assets/images/layer.png +0 -0
data/docs/assets/images/layer.svg +0 -35
data/docs/assets/prism-ruby.min.js +0 -1
data/docs/assets/styles.css +0 -347
data/docs/assets/vue.min.css +0 -1
data/docs/authorization_context.md +0 -92
data/docs/behaviour.md +0 -113
data/docs/caching.md +0 -291
data/docs/controller_action_aliases.md +0 -109
data/docs/custom_lookup_chain.md +0 -48
data/docs/custom_policy.md +0 -53
data/docs/debugging.md +0 -55
data/docs/decorators.md +0 -27
data/docs/favicon.ico +0 -0
data/docs/graphql.md +0 -302
data/docs/i18n.md +0 -44
data/docs/index.html +0 -43
data/docs/instrumentation.md +0 -84
data/docs/lookup_chain.md +0 -22
data/docs/namespaces.md +0 -77
data/docs/non_rails.md +0 -28
data/docs/pre_checks.md +0 -57
data/docs/pundit_migration.md +0 -80
data/docs/quick_start.md +0 -118
data/docs/rails.md +0 -120
data/docs/reasons.md +0 -120
data/docs/scoping.md +0 -255
data/docs/testing.md +0 -390
data/docs/writing_policies.md +0 -107
data/gemfiles/jruby.gemfile +0 -8
data/gemfiles/rails42.gemfile +0 -9
data/gemfiles/rails6.gemfile +0 -8
data/gemfiles/railsmaster.gemfile +0 -6
data/lib/action_policy/ext/string_match.rb +0 -14
data/lib/action_policy/ext/yield_self_then.rb +0 -25

data/docs/i18n.md DELETED

@@ -1,44 +0,0 @@
-# I18n Support
-`ActionPolicy` integrates with [`i18n`][] to support localizable `full_messages` for [reasons](./reasons.md) and the execution result's `message`:
-```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/index.html DELETED

@@ -1,43 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Action Policy: authorization framework for Ruby/Rails applications</title>
-  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
-  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0" />
-  <meta itemprop="name" content="Action Policy" />
-  <meta property="og:title" content="Action Policy" />
-  <meta name="description" content="Athorization framework for Ruby/Rails application" />
-  <meta itemprop="description" content="Authorization framework for Ruby/Rails application" />
-  <meta property="og:description" content="Authorization framework for Ruby/Rails application" />
-  <meta itemprop="image" content="http://actionpolicy.evilmartians.io/assets/images/banner.png" />
-  <meta property="og:image" content="http://actionpolicy.evilmartians.io/assets/images/banner.png" />
-  <meta name="twitter:card" content="summary_large_image" />
-  <meta name="twitter:site" content="@palkan_tula" />
-  <meta name="twitter:creator" content="@palkan_tula" />
-  <meta property="og:site_name" content="Action Policy" />
-  <meta name="keywords" content="ruby, rails, authorization, open-source" />
-  <meta name="theme-color" content="#CB2028" />
-  <link rel="stylesheet" href="assets/vue.min.css">
-  <link rel="stylesheet" href="assets/styles.css">
-</head>
-<body>
-  <div id="app"></div>
-  <script>
-    window.$docsify = {
-      name: 'action_policy',
-      repo: 'https://github.com/palkan/action_policy',
-      loadSidebar: true,
-      subMaxLevel: 3,
-      ga: 'UA-104346673-3',
-      auto2top: true,
-      search: {
-        namespace: 'action-policy'
-      }
-    }
-  </script>
-  <script src="assets/docsify.min.js"></script>
-  <script src="assets/docsify-search.js"></script>
-  <script src="assets/prism-ruby.min.js"></script>
-</body>
-</html>

data/docs/instrumentation.md DELETED

@@ -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 DELETED

@@ -1,22 +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`:
-    a) Try `"#{target.to_s.camelize}Policy"` as a `policy_name` (see below);
-    b) If `String#classify` is available, e.g. when using Rails' ActiveSupport, try `"#{target.to_s.classify}Policy"`;
-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 DELETED

@@ -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 < ApplicationController
-    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 < ApplicationController
-      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 DELETED

@@ -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 DELETED

@@ -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 DELETED

@@ -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 DELETED

@@ -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
-```