regulator 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 911cd1700d6c57b00ca93599c53af6b38aeb5e29
-  data.tar.gz: 483493a6ff6ddc269e374fedb22a3df20b917f6a
+  metadata.gz: 10e47763e8d217437980f1f09a6a7c4ab32ba1a2
+  data.tar.gz: f7326022562fbef9b9d0e386592fce817715316c
 SHA512:
-  metadata.gz: 5b2d0979c34ac379599b231e43aa79954a247a5c4bcac14379cce38a264d462258f98ee9e474f7954a84c1ea2df92630efb9c8ac55e021f2f67fb5d423e20143
-  data.tar.gz: 3ea1165fa80b0d4caf10a07f9496dd623fe31f81c9c1cd49f3108eb7e046cd1fbbe448e3a718d735505f2f0d3da1f21cd967c53342881aa53416d8650e44acff
+  metadata.gz: 62e40309efbf5f2a5f31abd664e1f7c05ace0cfbfb9ed690e9eb419538c8d3ab92095499654b5d09aa40adae82c8a2f500ed5ef565e6eb850a88c379a7fd5744
+  data.tar.gz: 9a0ee8202586ced8b054792cd66e11f94fa315dc981ef9708b833c94073d97ad3b00c97a2eec56819d60a3666cd10d5a66d043e4e488d54702cffaa5553f645c

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Regulator
 
+## 0.1.3 (2015-07-29)
+- made Regulator::PolicyFinder.new a bit more nimble
+- included a simple activeadmin adapter that can be 'required' instead of generated
+
 ## 0.1.2 (2015-07-23)
 - Add generators for install, policy, and activeadmin adapter
 

data/README.md

@@ -13,18 +13,6 @@ I built this because I believe authorization should be controller-based, not mod
 
 Why not contribute to pundit? [It's](https://github.com/elabs/pundit/issues/12) [been](https://github.com/elabs/pundit/issues/178) an [on going](https://github.com/elabs/pundit/search?q=namespace&type=Issues&utf8=%E2%9C%93) 'issue' in pundit and it doesn't look [like it'll be reality.](https://github.com/elabs/pundit/pull/190#issuecomment-53052356)
 
-## TODOs
-  * [ ] documentation
-    * [ ] Usage section below, mock pundit's
-    * [ ] yard doc
-    * [ ] Lotus examples
-    * [ ] Grape examples
-    * [ ] ROM examples
-    * [ ] Custom permissions examples
-    * [ ] RoleModel gem examples
-    * [ ] rolify gem examples
-  * [ ] contributing wiki
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -32,7 +20,6 @@ Add this line to your application's Gemfile:
 ```ruby
 gem 'regulator'
 ```
-
 And then execute:
 
     $ bundle
@@ -41,24 +28,29 @@ Or install it yourself as:
 
     $ gem install regulator
 
-## Usage
+Include Regulator in your application controller:
 
-No docs yet, check out the [specs](https://github.com/coryodaniel/regulator/blob/master/spec/regulator_spec.rb)
+``` ruby
+class ApplicationController < ActionController::Base
+  include Regulator
+  protect_from_forgery
+end
+```
 
-### Generators
+## Generators
 
 Install regulator
-```bash
+``` sh
   rails g regulator:install
 ```
 
 Create a new policy and policy test/spec
-```bash
+``` sh
   rails g regulator:policy User
 ```
 
 Regulator comes with a generator for creating an ActiveAdmin adapter
-```bash
+``` sh
   rails g regulator:activeadmin
 ```
 
@@ -84,6 +76,177 @@ config.regulator_policy_namespace = nil
 config.regulator_default_policy = nil
 ```
 
+## Policies
+
+Regulator is focused around the notion of policy classes. We suggest that you put
+these classes in `app/policies`. This is a simple example that allows updating
+a post if the user is an admin, or if the post is unpublished:
+
+``` ruby
+class PostPolicy
+  attr_reader :user, :post
+
+  def initialize(user, post)
+    @user = user
+    @post = post
+  end
+
+  def update?
+    user.admin? or not post.published?
+  end
+end
+```
+
+Regulator makes the following assumptions about this class:
+
+- The class has the name `Scope` and is nested under the policy class.
+- The first argument is a user. In your controller, Regulator will call the
+  `current_user` method to retrieve what to send into this argument.
+- The second argument is a scope of some kind on which to perform some kind of
+  query. It will usually be an ActiveRecord class or a
+  `ActiveRecord::Relation`, but it could be something else entirely.
+- Instances of this class respond to the method `resolve`, which should return
+  some kind of result which can be iterated over. For ActiveRecord classes,
+  this would usually be an `ActiveRecord::Relation`.
+
+You'll probably want to inherit from the application policy scope generated by the
+generator, or create your own base class to inherit from:
+
+``` ruby
+class PostPolicy < ApplicationPolicy
+  class Scope < Scope
+    def resolve
+      if user.admin?
+        scope.all
+      else
+        scope.where(:published => true)
+      end
+    end
+  end
+
+  def update?
+    user.admin? or not post.published?
+  end
+end
+```
+
+You can now use this class from your controller via the `policy_scope` method:
+
+``` ruby
+def index
+  @posts = policy_scope(Post)
+end
+```
+
+Just as with your policy, this will automatically infer that you want to use
+the `PostPolicy::Scope` class, it will instantiate this class and call
+`resolve` on the instance. In this case it is a shortcut for doing:
+
+``` ruby
+def index
+  @posts = PostPolicy::Scope.new(current_user, Post).resolve
+end
+```
+
+You can, and are encouraged to, use this method in views:
+
+``` erb
+<% policy_scope(@user.posts).each do |post| %>
+  <p><%= link_to post.title, post_path(post) %></p>
+<% end %>
+```
+
+## Manually specifying policy classes
+
+Sometimes you might want to explicitly declare which policy to use for a given
+class, instead of letting Regulator infer it. This can be done like so:
+
+Regulator supports the Pundit-style model "policy_class", but also implements it
+at the controller level. You can also set a controller's policy_namespace if you want to use an alternate namespace to the one the controller is in.
+
+
+``` ruby
+# Model level
+class Post
+  def self.policy_class
+    PostablePolicy
+  end
+end
+```
+
+``` ruby
+# Controller level
+class Api::Post
+  # By default, Regulator will look for Api::PostPolicy
+  def self.policy_class
+    PostPolicy
+  end
+end
+```
+
+``` ruby
+# Here the admin namespace could be told to use the same policy as the API namespace
+class Admin::Post
+  # By default, Regulator will look for Admin::PostPolicy
+  def self.policy_class
+    PostPolicy
+  end
+
+  # You can also set it at the instance level
+  def policy_class
+    if current_user.is_a_high_paying_member?
+      HighClassPostPolicy
+    else
+      LowClassPostPolicy
+    end
+  end
+end
+```
+
+``` ruby
+class Admin::Comment
+  def self.policy_namespace
+    # Will make regulator look for ActiveAdmin::CommentPolicy instead of
+    # Admin::CommentPolicy
+    ActiveAdmin
+  end
+end
+```
+
+Of course ```policy_namespace``` and ```policy_class``` can be used together.
+
+## Policy Namespaces
+
+This table explains what policies Regulator will look for in different scenarios:
+
+| Controller Name                                        | Model Name       | Expected Policy                |
+| -------------------------------------------------------|------------------| -------------------------------|
+| AlbumController                                        | Album            |  AlbumPolicy                   |
+| Api::AlbumController                                   | Album            |  Api::AlbumPolicy              |
+| Admin::AlbumController                                 | Album            |  Admin::AlbumPolicy            |
+| Admin::AlbumController.policy_namespace = 'SuperUser'  | Album            |  SuperUser::AlbumPolicy        |
+| Admin::AlbumController.policy_namespace = nil          | Album            |  AlbumPolicy                   |
+| Admin::AlbumContoller                                  | MySongGem::Album |  Admin::MySongGem::AlbumPolicy |
+| SongController#policy_class = TrackPolicy              | Song             |  TrackPolicy                   |
+| SongController.policy_class = Legacy::TrackPolicy      | Song             |  Legacy::TrackPolicy           |
+
+```policy_class``` at the controller-level is king. Setting it will override all logic for determining the policy to use.
+
+## ActiveAdmin Auth Adapter
+
+There is a generator and an included adapter. Using the generator will place a more complex customizable adapter in your ```lib``` directory.
+
+A simple adapter is also provided, to use add the following to your active_admin initializer:
+``` ruby
+ActiveAdmin::Dependency.regulator!
+
+require 'regulator'
+require 'regulator/active_admin_adapter'
+ActiveAdmin.setup do |config|
+  config.authorization_adapter = "Regulator::ActiveAdminAdapter"
+  ...
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -96,7 +259,19 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 ## Contributors
   * [Cory O'Daniel](http://linkedin.com/in/coryodaniel)
+  * All the hard work done on [Pundit](https://github.com/elabs/pundit)
 
   Thanks to Warren G for the inspiration, bro.
 
   ![Regulator](https://upload.wikimedia.org/wikipedia/commons/a/ac/Nat_Powers_%26_Warren_G.jpg)
+
+## TODOs
+  * [ ] documentation
+    * [ ] yard doc
+    * [ ] Lotus examples
+    * [ ] Grape examples
+    * [ ] ROM examples
+    * [ ] Custom permissions examples
+    * [ ] RoleModel gem examples
+    * [ ] rolify gem examples
+  * [ ] contributing wiki

data/lib/regulator/active_admin_adapter.rb

@@ -0,0 +1,34 @@
+module Regulator
+  class ActiveAdminAdapter < ActiveAdmin::AuthorizationAdapter
+    def authorized?(action, subject = nil)
+      policy = retrieve_policy(subject)
+      action = format_action(action, subject)
+      policy.respond_to?(action) && policy.public_send(action)
+    end
+
+    def scope_collection(collection, action = Auth::READ)
+      # scoping is appliable only to read/index action
+      # which means there is no way how to scope other actions
+      Regulator.policy_scope!(user, collection, self.resource.controller)
+    end
+
+    def retrieve_policy(subject)
+      case subject
+      when nil   then Regulator.policy!(user, resource, self.resource.controller)
+      when Class then Regulator.policy!(user, subject.new, self.resource.controller)
+      else Regulator.policy!(user, subject, self.resource.controller)
+      end
+    end
+
+    def format_action(action, subject)
+      # https://github.com/elabs/regulator/blob/master/lib/generators/regulator/install/templates/application_policy.rb
+      case action
+      when ActiveAdmin::Auth::CREATE  then :create?
+      when ActiveAdmin::Auth::UPDATE  then :update?
+      when ActiveAdmin::Auth::READ    then subject.is_a?(Class) ? :index? : :show?
+      when ActiveAdmin::Auth::DESTROY then subject.is_a?(Class) ? :destroy_all? : :destroy?
+      else "#{action}?"
+      end
+    end
+  end
+end

data/lib/regulator/policy_finder.rb

@@ -7,11 +7,31 @@ module Regulator
     def initialize(object, controller_or_namespace = nil)
       @object = object
 
-      if controller_or_namespace.is_a?(Module)
+      if controller_or_namespace.instance_of? Module
+        # Its a Module
         @namespace = controller_or_namespace
+      elsif controller_or_namespace.instance_of? Class
+        # Controller Class
+        @controller = controller_or_namespace
+
+        # ActiveAdmin uses the Regulator API directly, it doesnt mix it into the controllers
+        @namespace = if @controller.respond_to?(:policy_namespace)
+          # if the controller explicitly sets the policy_namespace to we want to keep it nil
+          @controller.try(:policy_namespace)
+        else
+          @controller.parent
+        end
       elsif controller_or_namespace
+        # Controller Instance
         @controller = controller_or_namespace
-        @namespace  = @controller.policy_namespace
+
+        # ActiveAdmin uses the Regulator API directly, it doesnt mix it into the controllers
+        @namespace = if @controller.respond_to?(:policy_namespace)
+          # if the controller explicitly sets the policy_namespace to we want to keep it nil
+          @controller.try(:policy_namespace)
+        else
+          @controller.class.parent
+        end
       end
     end
 

data/lib/regulator/version.rb

@@ -1,3 +1,3 @@
 module Regulator
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: regulator
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Cory O'Daniel
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-07-23 00:00:00.000000000 Z
+date: 2015-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -159,6 +159,7 @@ files:
 - lib/generators/test_unit/policy_generator.rb
 - lib/generators/test_unit/templates/policy_test.rb
 - lib/regulator.rb
+- lib/regulator/active_admin_adapter.rb
 - lib/regulator/policy_finder.rb
 - lib/regulator/rspec.rb
 - lib/regulator/version.rb