pundit_roles 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d24862dda5081913834ff5fc0063cc46c98e81c0
-  data.tar.gz: 8a426b027d8cf4889d4b11c466e11e6492dfa5fc
+  metadata.gz: 73b78e648f853870e204510432f843c7a003b32f
+  data.tar.gz: 5ca295739ef6482eeceffc70b2d49726bb672fcd
 SHA512:
-  metadata.gz: 41103de643378f38f4f55306f39010301a15ed09d4bc89c7effe183a29c011f0293fbbc478e4e0e925fab4f4e9d51647622d4ae4c66fd502798902b8b1817bea
-  data.tar.gz: 46fa3a352eb53d5d7a098d990255c96a4572793c0a20df4f3f6cb7b7712a9c9eb945670908e0fd6aadea2e6d9655e01c724f0f9eb1b5684e6d5e5d8b7c975e9a
+  metadata.gz: 9d37558263e616455f8fd07e155fa7529ff1e0a262c38978b6a4cc04a85f2dd91f42a17f68c8bfcda0012f3594ec2226393b644176ee81c79590103481436e53
+  data.tar.gz: '084bd79f07ce70c8d583dc8c460b2fd6e22940854886dcf2970633c220be539ac98902c630db5575a1e71e981759d285ac6d68d4f1f5598af4ed828c5e337fee'

data/CHANGELOG.md

@@ -8,7 +8,7 @@
 - Roles can no longer be inherited from the superclass.
 - Test conditions for the roles are now guessed from the name of the role, 
   instead of being declared explicitly with the `authorize_with` option.
-- Policy instance variable @record renamed @resource
+- Policy instance variable `@record` renamed `@resource`
 
 ## 0.5.0 (2017-11-08)
 

data/README.md

@@ -1,6 +1,6 @@
 # PunditRoles
 
-[![Gem Version](https://badge.fury.io/rb/pundit_roles.svg)](https://badge.fury.io/rb/pundit_roles.svg)
+[![Gem Version](https://badge.fury.io/rb/pundit_roles.svg)](https://rubygems.org/gems/pundit_roles)
 [![Build Status](https://travis-ci.org/StairwayB/pundit_roles.svg?branch=master)](https://travis-ci.org/StairwayB/pundit_roles)
 [![Coverage Status](https://coveralls.io/repos/github/StairwayB/pundit_roles/badge.svg?branch=master)](https://coveralls.io/github/StairwayB/pundit_roles?branch=master)
 [![Maintainability](https://api.codeclimate.com/v1/badges/030ffce3612160c8e7f0/maintainability)](https://codeclimate.com/github/StairwayB/pundit_roles/maintainability)
@@ -12,7 +12,7 @@ helpers for convenience.
 
 If you are already using Pundit, this should not conflict with any of Pundit's existing functionality. 
 You may use Pundit's features as well as the features from this gem interchangeably. There are
-some caveats however, see the [Porting over from Pundit](#Porting over from Pundit).
+some caveats however, see the [Porting over from Pundit](#porting-over-from-pundit).
 
 Please note that this gem is not affiliated with Pundit or it's creators, but it very much
 appreciates the work that they did with their great authorization system.
@@ -43,8 +43,8 @@ end
 
 PunditRoles operates around the notion of _**roles**_. Each role needs to be defined at the Policy level
 and provided with a conditional method that determines whether the `@user`(the `current_user` in the context of a Policy) 
-falls into this role. Additionally, each role can have a set of permitted 
-_**attributes**_ and _**associations**_ defined for it. A basic example for a UserPolicy would be:
+falls into this role. Additionally, each role can have a set of options defined for it(like _attributes_,
+_associations_ and _scope_). A basic example for a UserPolicy would be:
 ```ruby
 class UserPolicy < ApplicationPolicy
   role :regular_user,
@@ -53,45 +53,36 @@ class UserPolicy < ApplicationPolicy
        },
        associations: {
          show: %i(posts followers following)
-       }
+       },
+       scope: lambda{resource.regular_user_scope}
 
-role :correct_user,
+  role :correct_user,
        attributes: {
-         show: %i(email phone_number confirmed_at updated_at sign_in_count),
+         show: %i(email phone_number confirmed_at updated_at),
          update: %i(username email password password_confirmation current_password name avatar)
        },
        associations: {
          show: %i(settings),
          save: %i(settings)
        }
-end
-```
-
-This assumes that there are two methods defined in the UserPolicy called `regular_user?` and
-`correct_user?`.
-
-* Please note, that there were a couple of breaking change since `0.2.1`. View the 
-[changelog](https://github.com/StairwayB/pundit_roles/blob/master/CHANGELOG.md) for additional details.
-
-And then in you query method, you simply say:
-```ruby
-def show?
-  %i(user correct_user)
-end
+  
+  # in the query methods, you define the roles which are allowed for the particular action
+  def show?
+    %i(regular_user correct_user)
+  end
 
-def update?
-  %i(correct_user)
-end
-```
-Or you may use the `allow` helper method:
-```ruby
-def show?
-  allow :user, :correct_user
+  # or with the allow helper method:
+  def update?
+    allow :correct_user, :some_other_role
+  end
 end
 ```
 
-Finally, in your controller you call `authorize!` method and pass it's return value
-to a variable: 
+* This assumes that there are two methods defined in the UserPolicy called `regular_user?` and
+`correct_user?`. More on that in the [Defining roles](#defining-roles) section. 
+* How scopes work can be found in the [Scopes](#scopes) section. 
+
+Then in your controller you call the `authorize!` method and pass it's return value to a variable: 
 ```ruby
 class UserController < ApplicationController
   def show
@@ -102,8 +93,13 @@ class UserController < ApplicationController
 end
 ```
 
+* Please note, that there were a couple of breaking change since `0.2.1`. View the 
+[changelog](https://github.com/StairwayB/pundit_roles/blob/master/CHANGELOG.md) for additional details.
+
 The `authorize!` method will return a hash of permitted attributes and associations for the corresponding action that the
-user has access to. What you do with that is your business. Accessors for each segment look like this: 
+user has access to. What you do with that is your business. You may pass this hash to a serializer to limit what attributes
+are returned, or use it to sanitize create and update parameters(see the [Strong params](#strong-params) section).
+Accessors for each segment look like this: 
 ```ruby
 permitted[:attributes][:show] # ex. returns => [:username, :name, :avatar, :is_confirmed, :created_at]
 permitted[:attributes][:create] # ex. returns => [:username, :email, :password, :password_confirmation]
@@ -117,7 +113,8 @@ The hash also contains the roles that the user has fulfilled:
 permitted[:roles] # ex. returns => [:regular_user, :correct_user]
 ```
 
-If the user does not fall into any roles permitted by a query, the `authorize` method will raise `Pundit::NotAuthorizedError`
+If the user does not fall into any roles permitted by a query, the `authorize!` method will raise
+`Pundit::NotAuthorizedError`
 
 ### Defining roles
 
@@ -135,11 +132,20 @@ role :correct_user,
       attributes: {show: [:name]},
       associations: {show: [:posts]}
 
+role :admin_user
+      attributes: {show: [:name]},
+      associations: {show: [:posts]},
+      scope: lambda{resource.admin_scope}
+
 private
 
 def correct_user?
   @user.id == @resource.id
 end
+
+def admin_user?
+  @user.admin?
+end
 ```
 
 One thing to watch out for is that roles are not inherited, because each is unique to the model in question. 
@@ -147,7 +153,7 @@ But since the name of the role is just the conditional method for the role,
 without the '?' question mark, it is encouraged to inherit from an `ApplicationPolicy`, 
 and define common `role` conditionals there. 
 
-* see [Declaring attributes and associations](#Declaring attributes and associations) for how to declare 
+* see [Declaring attributes and associations](#declaring-attributes-and-associations) for how to declare 
 attributes and associations.
 
 ### Users with multiple roles
@@ -236,6 +242,7 @@ role :guest,
     },
     associations: {},
     scope: lambda{resource.where(visible_publicly: true)}
+
 role :regular_user,
    attributes: {
      show: %i(username name avatar)
@@ -269,9 +276,10 @@ end
 
 #### Important: Scope declaration order
 
-While attributes and associations for roles are merged, scopes are **not**! This means that whenever you wish to authorize a list of records,
-you must take care in what order you define the roles. PunditRoles will go over the allowed roles in a query method in the
-order in which they were defined, and when it finds a role that the user fulfills, it will return the scope for that role.
+While attributes and associations for roles are merged, scopes are **not**! This means that whenever you wish to authorize a 
+list of records,you must take care in what order you define the roles. PunditRoles will go over the allowed roles in a query 
+method in the order in which they were defined, and when it finds a role that the user fulfills, 
+it will return the scope for that role.
 
 Take this example, where there are two roles permitted for an `index` action: `regular_user` and `:admin_user`:
 ```ruby
@@ -296,8 +304,8 @@ end
 
 Whenever an admin tries to access the `index` action, PunditRoles will first check if the admin is a `regular_user`,
 which will be true, since admin is in fact logged in. Therefore, it will return the scope defined for `regular_user`,
-instead of the scope defined for `admin_user`. This is not the desired behaviour. In order to avoid this, the `index?` method
-needs to look like this:
+instead of the scope defined for `admin_user`. This is not the desired behaviour. In order to avoid this, the `index?` 
+method needs to look like this:
 ```ruby
 def index?
   allow :admin_user, :regular_user
@@ -311,17 +319,37 @@ meaning that there is no way that a user can fulfill more than one of these role
 does not matter. The guest role can be declared wherever, since PunditRoles will always evaluate whether the user is a 
 `guest` first. 
 
+### Strong params
+PunditRoles makes it easy to handle role-based strong params. Simply pass the `[:create]`, `[:update]` or `[:save]` 
+attribute of the `[:attributes]` attribute of the hash returned by the `authorize!` method to the params sanitizer
+(that's a mouthful).
+```ruby
+def create
+  permitted = authorize! User
+  @user = User.new(create_params(permitted[:attributes][:create]))
+  if @user.save!
+    render jsonapi: @user, fields: {users: permitted[:attributes][:show]}
+  end
+end
+
+private
+  
+def create_params(permitted_params)
+  params.require(:users).permit(permitted_params)
+end
+```
+
 ### Declaring attributes and associations
 
 * Attributes and associations in this heading are referred to collectively as _options_
 
-##### Explicit declaration of options
+#### Explicit declaration of options
 
 Options are declared with the `attributes` and `associations` options of the role method.
 
 Valid options for both `:attributes` and `:associations` are `:show`,`:create`,`:update` and `:save` or the implicit options.
 
-##### Implicit declaration of options
+#### Implicit declaration of options
 
 PunditRoles provides a set of helpers to be able to implicitly declare the options of a role. 
 

data/lib/pundit_roles/version.rb

@@ -1,3 +1,3 @@
 module PunditRoles
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pundit_roles
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Daniel Balogh