action_policy 0.4.3 → 0.5.3

data/docs/caching.md

@@ -1,291 +0,0 @@
-# Caching
-
-Action Policy aims to be as performant as possible. One of the ways to accomplish that is to include a comprehensive caching system.
-
-There are several cache layers available: rule-level memoization, local (instance-level) memoization, and _external_ cache (through cache stores).
-
-<div class="chart-container">
-  <img src="assets/images/cache.svg" alt="Cache layers" width="60%">
-</div>
-
-## Policy memoization
-
-### Per-instance
-
-There could be a situation when you need to apply the same policy to the same record multiple times during the action (e.g., request). For example:
-
-```ruby
-# app/controllers/posts_controller.rb
-class PostsController < ApplicationController
-  def show
-    @post = Post.find(params[:id])
-    authorize! @post
-    render :show
-  end
-end
-```
-
-```erb
-# app/views/posts/show.html.erb
-<h1><%= @post.title %>
-
-<% if allowed_to?(:edit?, @post) %>
-  <%= link_to "Edit", @post %>
-<% end %>
-
-<% if allowed_to?(:destroy?, @post) %>
-  <%= link_to "Delete", @post, method: :delete %>
-<% end %>
-```
-
-In the above example, we need to use the same policy three times. Action Policy re-uses the policy instance to avoid unnecessary object allocation.
-
-We rely on the following assumptions:
-- parent object (e.g., a controller instance) is _ephemeral_, i.e., it is a short-lived object
-- all authorizations use the same [authorization context](authorization_context.md).
-
-We use `record.policy_cache_key` with fallback to `record.cache_key` or `record.object_id` as a part of policy identifier in the local store.
-
-**NOTE**: policies memoization is an extension for `ActionPolicy::Behaviour` and could be included with `ActionPolicy::Behaviours::Memoized`.
-
-**NOTE**: memoization is automatically included into Rails controllers integration, but not included into channels integration, since channels are long-lived objects.
-
-### Per-thread
-
-Consider a more complex situation:
-
-```ruby
-# app/controllers/comments_controller.rb
-class CommentsController < ApplicationController
-  def index
-    # all comments for all posts
-    @comments = Comment.all
-  end
-end
-```
-
-```erb
-# app/views/comments/index.html.erb
-<% @comments.each do |comment| %>
-  <li><%= comment.text %>
-    <% if allowed_to?(:edit?, comment) %>
-      <%= link_to comment, "Edit" %>
-    <% end %>
-  </li>
-<% end %>
-```
-
-```ruby
-# app/policies/comment_policy.rb
-class CommentPolicy < ApplicationPolicy
-  def edit?
-    user.admin? || (user.id == record.id) ||
-      allowed_to?(:manage?, record.post)
-  end
-end
-```
-
-In some cases, we have to initialize **two** policies for each comment: one for the comment itself and one for the comment's post (in the `allowed_to?` call).
-
-That is an example of a _N+1 authorization_ problem, which in its turn could easily cause a _N+1 query_ problem (if `PostPolicy#manage?` makes database queries). Sounds terrible, doesn't it?
-
-It is likely that many comments belong to the same post. If so, we can move our memoization one level up and use local thread store.
-
-Action Policy provides `ActionPolicy::Behaviours::ThreadMemoized` module with this functionality (included into Rails controllers integration by default).
-
-If you want to add this behavior to your custom authorization-aware class, you should care about cleaning up the thread store manually (by calling `ActionPolicy::PerThreadCache.clear_all`).
-
-**NOTE:** per-thread cache is disabled by default in test environment (when either `RACK_ENV` or `RAILS_ENV` environment variable is equal to "test").
-You can turn it on (or off) by setting:
-
-```ruby
-ActionPolicy::PerThreadCache.enabled = true # or false to disable
-```
-
-## Rule cache
-
-### Per-instance
-
-There could be a situation when the same rule is called multiple times for the same policy instance (for example, when using [aliases](aliases.md)).
-
-In that case, Action Policy invokes the rule method only once, remembers the result, and returns it immediately for the subsequent calls.
-
-**NOTE**: rule results memoization is available only if you inherit from `ActionPolicy::Base` or include `ActionPolicy::Policy::CachedApply` into your `ApplicationPolicy`.
-
-### Using the cache store
-
-Some policy rules might be _performance-heavy_, e.g., make complex database queries.
-
-In that case, it makes sense to cache the rule application result for a long time (not just for the duration of a request).
-
-Action Policy provides a way to use _cache stores_ for that. You have to explicitly define which rules you want to cache in your policy class. For example:
-
-```ruby
-class StagePolicy < ApplicationPolicy
-  # mark show? rule to be cached
-  cache :show?
-  # you can also provide store-specific options
-  # cache :show?, expires_in: 1.hour
-
-  def show?
-    full_access? ||
-      user.stage_permissions.where(
-        stage_id: record.id
-      ).exists?
-  end
-
-  private
-
-  def full_access?
-    !record.funnel.is_private? ||
-      user.permissions
-        .where(
-          funnel_id: record.funnel_id,
-          full_access: true
-        ).exists?
-  end
-end
-```
-
-You must configure a cache store to use this feature:
-
-```ruby
-ActionPolicy.cache_store = MyCacheStore.new
-```
-
-Or, in Rails:
-
-```ruby
-# config/application.rb (or config/environments/<environment>.rb)
-Rails.application.configure do |config|
-  config.action_policy.cache_store = :redis_cache_store
-end
-```
-
-Cache store must provide at least a `#read(key)` and `write(key, value, **options)` methods.
-
-**NOTE:** cache store also should take care of serialiation/deserialization since the `value` is `ExecutionResult` instance (which contains also some additional information, e.g. failure reasons). Rails cache store supports serialization/deserialization out-of-the-box.
-
-By default, Action Policy builds a cache key using the following scheme (defined in `#rule_cache_key(rule)` method):
-
-```ruby
-"#{cache_namespace}/#{context_cache_key}" \
-"/#{record.policy_cache_key}/#{policy.class.name}/#{rule}"
-```
-
-Where `cache_namespace` is equal to `"acp:#{MAJOR_GEM_VERSION}.#{MINOR_GEM_VERSION}"`, and `context_cache_key` is a concatenation of all authorization contexts cache keys (in the same order as they are defined in the policy class).
-
-If any object does not respond to `#policy_cache_key`, we fallback to `#cache_key` (or `#cache_key_with_version` for modern Rails versions). 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 `rule_cache_key` / `cache_namespace` / `context_cache_key` methods for policy class to override this logic.
-
-You can also use the `#cache` instance method to cache arbitrary values in you policies:
-
-```ruby
-class ApplicationPolicy < ActionPolicy::Base
-  # Suppose that a user has many roles each having an array of permissions
-  def permissions
-    cache(user) { user.roles.pluck(:permissions).flatten.uniq }
-  end
-
-  # You can pass multiple cache key "parts"
-  def account_permissions(account)
-    cache(user, account) { user.account_roles.where(account: account).pluck(:permissions).flatten.uniq }
-  end
-end
-```
-
-**NOTE:** `#cache` method uses the same cache key generation logic as rules caching (described above).
-
-#### Invalidation
-
-There no one-size-fits-all solution for invalidation. It highly depends on your business logic.
-
-**Case \#1**: no invalidation required.
-
-First of all, you should try to avoid manual invalidation at all. That could be achieved by using elaborate cache keys.
-
-Let's consider an example.
-
-Suppose that your users have _roles_ (i.e. `User.belongs_to :role`) and you give access to resources through the `Access` model (i.e. `Resource.has_many :accesses`).
-
-Then you can do the following:
-- Keep tracking the last `Access` added/updated/deleted for resource (e.g. `Access.belongs_to :accessessable, touch: :access_updated_at`)
-- Use the following cache keys:
-
-```ruby
-class User
-  def policy_cache_key
-    "user::#{id}::#{role_id}"
-  end
-end
-
-class Resource
-  def policy_cache_key
-    "#{resource.class.name}::#{id}::#{access_updated_at}"
-  end
-end
-```
-
-**Case \#2**: discarding all cache at once.
-
-That's pretty easy: just override `cache_namespace` method in your `ApplicationPolicy` with the new value:
-
-```ruby
-class ApplicationPolicy < ActionPolicy::Base
-  # It's a good idea to store the changing part in the constant
-  CACHE_VERSION = "v2".freeze
-
-  # or even from the env variable
-  # CACHE_VERSION = ENV.fetch("POLICY_CACHE_VERSION", "v2").freeze
-
-  def cache_namespace
-    "action_policy::#{CACHE_VERSION}"
-  end
-end
-```
-
-**Case \#3**: discarding some keys.
-
-That is an alternative approach to _crafting_ cache keys.
-
-If you have a limited number of places in your application where you update access control,
-you can invalidate policies cache manually. If your cache store supports `delete_matched` command (deleting keys using a wildcard), you can try the following:
-
-```ruby
-class ApplicationPolicy < ActionPolicy::Base
-  # Define custom cache key generator
-  def cache_key(rule)
-    "policy_cache/#{user.id}/#{self.class.name}/#{record.id}/#{rule}"
-  end
-end
-
-class Access < ApplicationRecord
-  belongs_to :resource
-  belongs_to :user
-
-  after_commit :cleanup_policy_cache, on: [:create, :destroy]
-
-  def cleanup_policy_cache
-    # Clear cache for the corresponding user-record pair
-    ActionPolicy.cache_store.delete_matched(
-      "policy_cache/#{user_id}/#{ResourcePolicy.name}/#{resource_id}/*"
-    )
-  end
-end
-
-class User < ApplicationRecord
-  belongs_to :role
-
-  after_commit :cleanup_policy_cache, on: [:update], if: :role_id_changed?
-
-  def cleanup_policy_cache
-    # Clear all policies cache for user
-    ActionPolicy.cache_store.delete_matched(
-      "policy_cache/#{user_id}/*"
-    )
-  end
-end
-```

data/docs/controller_action_aliases.md

@@ -1,109 +0,0 @@
-# Controller Action Aliases
-
-**This is a feature proposed here: https://github.com/palkan/action_policy/issues/25**
-
-If you'd like to see this feature implemented, please comment on the issue to show your support.
-
-## Outline
-
-Say you have abstracted your `authorize!` call to a controller superclass because your policy can
-be executed without regard to the record in any of the subclass controllers:
-
-```ruby
-class AbstractController < ApplicationController
-  authorize :context
-  before_action :authorize_context
-
-  def context
-    # Some code to get your policy context
-  end
-
-  private
-
-  def authorize_context
-    authorize! Context
-  end
-end
-```
-
-Your policy might look like this:
-
-```ruby
-class ContextPolicy < ApplicationPolicy
-  authorize :context
-
-  alias_rule :index?, :show?, to: :view?
-  alias_rule :new?, :create?, :update?, :destroy?, to: :edit?
-
-  def view?
-    context.has_permission_to(:view, user)
-  end
-
-  def edit?
-    context.has_permission_to(:edit, user)
-  end
-end
-```
-
-We can safely add aliases for the common REST actions in the policy.
-
-You may then want to include a concern in your subclass controller(s) that add extra actions to the controller.
-
-
-```ruby
-class ConcreteController < AbstractController
-  include AdditionalFunctionalityConcern
-
-  def index
-    # Index Action
-  end
-
-  def new
-    # New Action
-  end
-
-  # etc...
-end
-```
-
-At this point you may be wondering how to tell your abstracted policy that these new methods map to either
-the `view?` or `edit?` rule. You can currently provide the rule to execute to the `authorize!` method with
-the `to:` parameter but since our call to `authorize!` is in a superclass it has no idea about our concern.
-I propose the following controller method:
-
-```ruby
-alias_action(*actions, to_rule: rule)
-```
-
-Here's an example:
-
-```ruby
-module AdditionalFunctionalityConcern
-  extend ActiveSupport::Concern
-
-  included do
-    alias_action [:first_action, :second_action], to_rule: :view?
-    alias_action [:third_action], to_rule: :edit?
-  end
-
-  def first_action
-    # First Action
-  end
-
-  def second_action
-    # Second Action
-  end
-
-  def third_action
-    # Third Action
-  end
-end
-```
-
-When `authorize!` is called in a controller, it will first check the action aliases for a corresponding
-rule. If one is found, it will execute that rule instead of a rule matching the name of the current action.
-The rule may point at a concrete rule in the policy, or a rule alias in the policy, it doens't matter, the
-alias in the policy will be resolved like normal.
-
-If you'd like to see this feature implemented, please show your support on the
-[Github Issue](https://github.com/palkan/action_policy/issues/25).

data/docs/custom_lookup_chain.md

@@ -1,48 +0,0 @@
-# Custom Lookup Chain
-
-Action Policy's lookup chain is just an array of _probes_ (lambdas with a specific interface).
-
-The lookup process itself is pretty simple:
-- Call the first probe;
-- Return the result if it is not `nil`;
-- Go to the next probe.
-
-You can override the default chain with your own. For example:
-
-```ruby
-ActionPolicy::LookupChain.chain = [
-  # Probe accepts record as the first argument
-  # and arbitrary options (passed to `authorize!` / `allowed_to?` call)
-  lambda do |record, **options|
-    # your custom lookup logic
-  end
-]
-```
-
-## NullPolicy example
-
-Let's consider a simple example of extending the existing lookup chain with one more probe.
-
-Suppose that we want to have a fallback policy (policy used when none found for the resource) instead of raising an `ActionPolicy::NotFound` error.
-
-Let's call this policy a `NullPolicy`:
-
-```ruby
-class NullPolicy < ActionPolicy::Base
-  default_rule :any?
-
-  def any?
-    false
-  end
-end
-```
-
-Here we use the [default rule](aliases.md#default-rule) to handle any rule applied.
-
-Now we need to add a simple probe to the end of our lookup chain:
-
-```ruby
-ActionPolicy::LookupChain.chain << ->(_, _) { NullPolicy }
-```
-
-That's it!

data/docs/custom_policy.md

@@ -1,53 +0,0 @@
-# Custom Base Policy
-
-`ActionPolicy::Base` is a combination of all available policy extensions with the default configuration.
-
-It looks like this:
-
-
-```ruby
-class ActionPolicy::Base
-  include ActionPolicy::Policy::Core
-  include ActionPolicy::Policy::Authorization
-  include ActionPolicy::Policy::PreCheck
-  include ActionPolicy::Policy::Reasons
-  include ActionPolicy::Policy::Aliases
-  include ActionPolicy::Policy::Scoping
-  include ActionPolicy::Policy::Cache
-  include ActionPolicy::Policy::CachedApply
-  include ActionPolicy::Policy::Defaults
-
-  # ActionPolicy::Policy::Defaults module adds the following
-
-  authorize :user
-
-  default_rule :manage?
-  alias_rule :new?, to: :create?
-
-  def index?
-    false
-  end
-
-  def create?
-    false
-  end
-
-  def manage?
-    false
-  end
-end
-```
-
-
-
-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`:
-
-```ruby
-# minimal ApplicationPolicy
-class ApplicationPolicy
-  include ActionPolicy::Policy::Core
-end
-```
-
-The `Core` module provides `apply` and `allowed_to?` methods.