action_policy 0.3.4 → 0.4.4

data/docs/README.md

@@ -65,6 +65,8 @@ Learn more about the motivation behind the Action Policy and its features by wat
 
 ## Resources
 
+- RubyRussia, 2019 "Welcome, or access denied?" talk ([video](https://www.youtube.com/watch?v=y15a2g7v8i0) [RU], [slides](https://speakerdeck.com/palkan/rubyrussia-2019-welcome-or-access-denied))
+
 - Seattle.rb, 2019 "A Denial!" talk [[slides](https://speakerdeck.com/palkan/seattle-dot-rb-2019-a-denial)]
 
 - RailsConf, 2018 "Access Denied" talk [[video](https://www.youtube.com/watch?v=NVwx0DARDis), [slides](https://speakerdeck.com/palkan/railsconf-2018-access-denied-the-missing-guide-to-authorization-in-rails)]

data/docs/caching.md

@@ -162,11 +162,11 @@ Rails.application.configure do |config|
 end
 ```
 
-Cache store must provide at least a `#read(key)` and `write(key, value, **options)` methods.
+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:
+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}" \
@@ -175,11 +175,29 @@ By default, Action Policy builds a cache key using the following scheme:
 
 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`. If `#cache_key` is not defined, an `ArgumentError` is raised.
+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 `cache_key` / `cache_namespace` / `context_cache_key` methods for policy class to override this logic.
+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
 

data/docs/instrumentation.md

@@ -47,6 +47,17 @@ 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:

data/docs/lookup_chain.md

@@ -2,7 +2,12 @@
 
 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);
+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);

data/docs/namespaces.md

@@ -6,7 +6,7 @@ Consider an example:
 
 ```ruby
 module Admin
-  class UsersController < ApplictionController
+  class UsersController < ApplicationController
     def index
       # uses Admin::UserPolicy if any, otherwise fallbacks to UserPolicy
       authorize!
@@ -20,7 +20,7 @@ Module nesting is also supported:
 ```ruby
 module Admin
   module Client
-    class UsersController < ApplictionController
+    class UsersController < ApplicationController
       def index
         # lookup for Admin::Client::UserPolicy -> Admin::UserPolicy -> UserPolicy
         authorize!

data/docs/quick_start.md

@@ -34,9 +34,11 @@ class ApplicationPolicy < ActionPolicy::Base
 end
 ```
 
-You could use the following command to generate it.
+You could use the following command to generate it when using Rails:
 
-    $ rails generate action_policy:install
+```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.
 
@@ -96,7 +98,7 @@ There is also an `allowed_to?` method which returns `true` or `false` and could
 <% @posts.each do |post| %>
   <li><%= post.title %>
     <% if allowed_to?(:edit?, post) %>
-      = link_to "Edit", post
+      <%= link_to "Edit", post %>
     <% end %>
   </li>
 <% end %>

data/docs/rails.md

@@ -6,6 +6,13 @@ In most cases, you do not have to do anything except writing policy files and ad
 
 **NOTE:** both controllers and channels extensions are built on top of the Action Policy [behaviour](./behaviour.md) mixin.
 
+## Generators
+
+Action Policy provides a couple of useful Rails generators:
+
+- `rails g action_policy:install` — adds `app/policies/application_policy.rb` file
+- `rails g action_policy:policy MODEL_NAME` — adds a policy file and a policy test file for a given model (also creates an `application_policy.rb` if it's missing)
+
 ## Controllers integration
 
 Action Policy assumes that you have a `current_user` method which specifies the current authenticated subject (`user`).

data/docs/testing.md

@@ -112,6 +112,8 @@ OR
 
 ### Testing scopes
 
+#### Active Record relation example
+
 There is no single rule on how to test scopes, 'cause it dependes on the _nature_ of the scope.
 
 Here's an example of RSpec tests for Active Record scoping rules:
@@ -156,6 +158,35 @@ describe PostPolicy do
 end
 ```
 
+#### Action Controller params example
+
+Here's an example of RSpec tests for Action Controller parameters scoping rules:
+
+```ruby
+describe PostPolicy do
+  describe "params scope" do
+    let(:user) { build_stubbed :user }
+    let(:context) { {user: user} }
+
+    let(:params) { {name: "a", password: "b"} }
+    let(:target) { ActionController::Parameters.new(params) }
+
+    # it's easier to asses the hash representation, not the AC::Params object
+    subject { policy.apply_scope(target, type: :action_controller_params).to_h }
+
+    context "as user" do
+      it { is_expected.to eq({name: "a"}) }
+    end
+
+    context "as manager" do
+      before { user.update!(role: :manager) }
+
+      it { is_expected.to eq({name: "a", password: "b"}) }
+    end
+  end
+end
+```
+
 ## Testing authorization
 
 To test the act of authorization you have to make sure that the `authorize!` method is called with the appropriate arguments.
@@ -230,6 +261,12 @@ end
 
 If you omit `.with(PostPolicy)` then the inferred policy for the target (`post`) would be used.
 
+RSpec composed matchers are available as target:
+
+```ruby
+expect { subject }.to be_authorized_to(:show?, an_instance_of(Post))
+```
+
 ## Testing scoping
 
 Action Policy provides a way to test that a correct scoping has been applied during the code execution.
@@ -325,3 +362,29 @@ expect { subject }.to have_authorized_scope(:scope)
     expect(target).to eq(User.all)
   }
 ```
+
+
+## Testing views
+
+When you test views that call policies methods as `allowed_to?`, your may have `Missing policy authorization context: user` error.
+You may need to stub `current_user` to resolve the issue.
+
+Consider an RSpec example:
+
+```ruby
+describe "users/index.html.slim" do
+  let(:user) { build_stubbed :user }
+  let(:users) { create_list(:user, 2) }
+
+  before do
+    allow(controller).to receive(:current_user).and_return(user)
+
+    assign :users, users
+    render
+  end
+
+  describe "displays user#index correctly" do
+    it { expect(rendered).to have_link(users.first.email, href: edit_user_path(users.first)) }
+  end
+end
+```

data/docs/writing_policies.md

@@ -56,7 +56,7 @@ You can also specify all the usual options (such as `with`).
 
 There is also a `check?` method which is just an "alias"\* for `allowed_to?` added for better readability:
 
-```
+```ruby
 class PostPolicy < ApplicationPolicy
   def show?
     user.admin? || check?(:publicly_visible?)

data/gemfiles/rails42.gemfile

@@ -2,6 +2,7 @@ source "https://rubygems.org"
 
 gem "sqlite3", "~> 1.3.0"
 gem "rails", "~> 4.2"
+gem "thor", "< 1.0"
 gem "method_source"
 gem "unparser"
 

data/lib/action_policy.rb

@@ -31,7 +31,7 @@ module ActionPolicy
 
     # Find a policy class for a target
     def lookup(target, allow_nil: false, **options)
-      LookupChain.call(target, options) ||
+      LookupChain.call(target, **options) ||
         (allow_nil ? nil : raise(NotFound, target))
     end
   end

data/lib/action_policy/behaviour.rb

@@ -38,6 +38,8 @@ module ActionPolicy
       record = implicit_authorization_target! if record == :__undef__
       raise ArgumentError, "Record must be specified" if record.nil?
 
+      options[:context] && (options[:context] = authorization_context.merge(options[:context]))
+
       policy = policy_for(record: record, **options)
 
       Authorizer.call(policy, authorization_rule_for(policy, to))
@@ -50,6 +52,8 @@ module ActionPolicy
       record = implicit_authorization_target! if record == :__undef__
       raise ArgumentError, "Record must be specified" if record.nil?
 
+      options[:context] && (options[:context] = authorization_context.merge(options[:context]))
+
       policy = policy_for(record: record, **options)
 
       policy.apply(authorization_rule_for(policy, rule))

data/lib/action_policy/behaviours/memoized.rb

@@ -19,9 +19,6 @@ module ActionPolicy
     #
     #   policy.equal?(policy_for(record, with: CustomPolicy)) #=> false
     module Memoized
-      require "action_policy/ext/policy_cache_key"
-      using ActionPolicy::Ext::PolicyCacheKey
-
       class << self
         def prepended(base)
           base.prepend InstanceMethods
@@ -32,13 +29,12 @@ module ActionPolicy
 
       module InstanceMethods # :nodoc:
         def policy_for(record:, **opts)
-          __policy_memoize__(record, opts) { super(record: record, **opts) }
+          __policy_memoize__(record, **opts) { super(record: record, **opts) }
         end
       end
 
-      def __policy_memoize__(record, with: nil, namespace: nil, **_opts)
-        record_key = record._policy_cache_key(use_object_id: true)
-        cache_key = "#{namespace}/#{with}/#{record_key}"
+      def __policy_memoize__(record, **options)
+        cache_key = policy_for_cache_key(record: record, **options)
 
         return __policies_cache__[cache_key] if
           __policies_cache__.key?(cache_key)

data/lib/action_policy/behaviours/policy_for.rb

@@ -4,11 +4,13 @@ module ActionPolicy
   module Behaviours
     # Adds `policy_for` method
     module PolicyFor
+      require "action_policy/ext/policy_cache_key"
+      using ActionPolicy::Ext::PolicyCacheKey
+
       # Returns policy instance for the record.
-      def policy_for(record:, with: nil, namespace: nil, context: nil, **options)
-        namespace ||= authorization_namespace
-        policy_class = with || ::ActionPolicy.lookup(record, namespace: namespace, **options)
-        policy_class&.new(record, authorization_context.tap { |ctx| ctx.merge!(context) if context })
+      def policy_for(record:, with: nil, namespace: authorization_namespace, context: authorization_context, allow_nil: false)
+        policy_class = with || ::ActionPolicy.lookup(record, namespace: namespace, context: context, allow_nil: allow_nil)
+        policy_class&.new(record, **context)
       end
 
       def authorization_context
@@ -41,6 +43,13 @@ module ActionPolicy
           ]
         )
       end
+
+      def policy_for_cache_key(record:, with: nil, namespace: nil, context: authorization_context, **)
+        record_key = record._policy_cache_key(use_object_id: true)
+        context_key = context.values.map { |v| v._policy_cache_key(use_object_id: true) }.join(".")
+
+        "#{namespace}/#{with}/#{context_key}/#{record_key}"
+      end
     end
   end
 end

data/lib/action_policy/behaviours/scoping.rb

@@ -11,6 +11,8 @@ module ActionPolicy
       #   - secondly, try to infer policy class from `target` (non-raising lookup)
       #   - use `implicit_authorization_target` if none of the above works.
       def authorized_scope(target, type: nil, as: :default, scope_options: nil, **options)
+        options[:context] && (options[:context] = authorization_context.merge(options[:context]))
+
         policy = policy_for(record: target, allow_nil: true, **options)
         policy ||= policy_for(record: implicit_authorization_target!, **options)
 

data/lib/action_policy/behaviours/thread_memoized.rb

@@ -37,9 +37,6 @@ module ActionPolicy
     #
     # NOTE: don't forget to clear thread cache with ActionPolicy::PerThreadCache.clear_all
     module ThreadMemoized
-      require "action_policy/ext/policy_cache_key"
-      using ActionPolicy::Ext::PolicyCacheKey
-
       class << self
         def prepended(base)
           base.prepend InstanceMethods
@@ -50,13 +47,12 @@ module ActionPolicy
 
       module InstanceMethods # :nodoc:
         def policy_for(record:, **opts)
-          __policy_thread_memoize__(record, opts) { super(record: record, **opts) }
+          __policy_thread_memoize__(record, **opts) { super(record: record, **opts) }
         end
       end
 
-      def __policy_thread_memoize__(record, with: nil, namespace: nil, **_opts)
-        record_key = record._policy_cache_key(use_object_id: true)
-        cache_key = "#{namespace}/#{with}/#{record_key}"
+      def __policy_thread_memoize__(record, **options)
+        cache_key = policy_for_cache_key(record: record, **options)
 
         ActionPolicy::PerThreadCache.fetch(cache_key) { yield }
       end

data/lib/action_policy/ext/policy_cache_key.rb

@@ -13,19 +13,15 @@ module ActionPolicy
       module ObjectExt
         def _policy_cache_key(use_object_id: false)
           return policy_cache_key if respond_to?(:policy_cache_key)
+          return cache_key_with_version if respond_to?(:cache_key_with_version)
           return cache_key if respond_to?(:cache_key)
 
-          return object_id if use_object_id == true
+          return object_id.to_s if use_object_id == true
 
           raise ArgumentError, "object is not cacheable"
         end
       end
 
-      # JRuby doesn't support _global_ modules refinements (see https://github.com/jruby/jruby/issues/5220)
-      # Fallback to monkey-patching.
-      # TODO: remove after 9.2.7.0 (See https://github.com/jruby/jruby/pull/5627)
-      ::Object.include(ObjectExt) if RUBY_PLATFORM =~ /java/i
-
       refine Object do
         include ObjectExt
       end
@@ -85,6 +81,12 @@ module ActionPolicy
           to_s
         end
       end
+
+      refine Module do
+        def _policy_cache_key(*)
+          name
+        end
+      end
     end
   end
 end

data/lib/action_policy/ext/{symbol_classify.rb → symbol_camelize.rb}

@@ -2,15 +2,15 @@
 
 module ActionPolicy
   module Ext
-    # Add `classify` to Symbol
-    module SymbolClassify
+    # Add `camelize` to Symbol
+    module SymbolCamelize
       refine Symbol do
-        if "".respond_to?(:classify)
-          def classify
-            to_s.classify
+        if "".respond_to?(:camelize)
+          def camelize
+            to_s.camelize
           end
         else
-          def classify
+          def camelize
             word = to_s.capitalize
             word.gsub!(/(?:_)([a-z\d]*)/) { $1.capitalize }
             word

data/lib/action_policy/lookup_chain.rb

@@ -12,8 +12,8 @@ module ActionPolicy
       using ActionPolicy::Ext::StringConstantize
     end
 
-    require "action_policy/ext/symbol_classify"
-    using ActionPolicy::Ext::SymbolClassify
+    require "action_policy/ext/symbol_camelize"
+    using ActionPolicy::Ext::SymbolCamelize
 
     require "action_policy/ext/module_namespace"
     using ActionPolicy::Ext::ModuleNamespace
@@ -45,7 +45,7 @@ module ActionPolicy
 
       def call(record, **opts)
         chain.each do |probe|
-          val = probe.call(record, opts)
+          val = probe.call(record, **opts)
           return val unless val.nil?
         end
         nil
@@ -54,6 +54,7 @@ module ActionPolicy
       private
 
       def lookup_within_namespace(policy_name, namespace)
+        return unless namespace
         NamespaceCache.fetch(namespace.name, policy_name) do
           mod = namespace
 
@@ -88,12 +89,12 @@ module ActionPolicy
       !ENV["RACK_ENV"].nil? ? ENV["RACK_ENV"] == "production" : true
 
     # By self `policy_class` method
-    INSTANCE_POLICY_CLASS = ->(record, _) {
+    INSTANCE_POLICY_CLASS = ->(record, **) {
       record.policy_class if record.respond_to?(:policy_class)
     }
 
     # By record's class `policy_class` method
-    CLASS_POLICY_CLASS = ->(record, _) {
+    CLASS_POLICY_CLASS = ->(record, **) {
       record.class.policy_class if record.class.respond_to?(:policy_class)
     }
 
@@ -106,7 +107,7 @@ module ActionPolicy
     }
 
     # Infer from class name
-    INFER_FROM_CLASS = ->(record, _) {
+    INFER_FROM_CLASS = ->(record, **) {
       policy_class_name_for(record).safe_constantize
     }
 
@@ -114,20 +115,25 @@ module ActionPolicy
     SYMBOL_LOOKUP = ->(record, namespace: nil, **) {
       next unless record.is_a?(Symbol)
 
-      policy_name = "#{record.classify}Policy"
-      if namespace.nil?
-        policy_name.safe_constantize
-      else
-        lookup_within_namespace(policy_name, namespace)
-      end
+      policy_name = "#{record.camelize}Policy"
+      lookup_within_namespace(policy_name, namespace) || policy_name.safe_constantize
+    }
+
+    # (Optional) Infer using String#classify if available
+    CLASSIFY_SYMBOL_LOOKUP = ->(record, namespace: nil, **) {
+      next unless record.is_a?(Symbol)
+
+      policy_name = "#{record.to_s.classify}Policy"
+      lookup_within_namespace(policy_name, namespace) || policy_name.safe_constantize
     }
 
     self.chain = [
       SYMBOL_LOOKUP,
+      (CLASSIFY_SYMBOL_LOOKUP if String.method_defined?(:classify)),
       INSTANCE_POLICY_CLASS,
       CLASS_POLICY_CLASS,
       NAMESPACE_LOOKUP,
       INFER_FROM_CLASS
-    ]
+    ].compact
   end
 end