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

action_policy 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (100) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +233 -171
data/LICENSE.txt +1 -1
data/README.md +7 -11
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 +15 -33
data/lib/action_policy/ext/{symbol_classify.rb → symbol_camelize.rb} +6 -6
data/lib/action_policy/i18n.rb +1 -1
data/lib/action_policy/lookup_chain.rb +41 -21
data/lib/action_policy/policy/aliases.rb +7 -12
data/lib/action_policy/policy/authorization.rb +14 -17
data/lib/action_policy/policy/cache.rb +34 -18
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 +30 -20
data/lib/action_policy/policy/scoping.rb +5 -6
data/lib/action_policy/rails/controller.rb +6 -1
data/lib/action_policy/rails/ext/active_record.rb +7 -0
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 +3 -3
data/lib/action_policy/rspec/have_authorized_scope.rb +5 -7
data/lib/action_policy/testing.rb +1 -1
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} +1 -1
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 +30 -119
data/.gitattributes +0 -2
data/.github/FUNDING.yml +0 -1
data/.github/ISSUE_TEMPLATE.md +0 -18
data/.github/PULL_REQUEST_TEMPLATE.md +0 -29
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 -71
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 -77
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 -273
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 -17
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 -333
data/docs/writing_policies.md +0 -107
data/gemfiles/jruby.gemfile +0 -8
data/gemfiles/rails42.gemfile +0 -8
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,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 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 < 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 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
-```